How to use the command 'phploc' (with examples)

PHPLOC is a command-line utility designed for quickly measuring the size and analyzing the structure of a PHP project. Developed as an efficient tool for developers, it allows for rapid access to statistics concerning code complexity, the number of lines of code, and other relevant details essential for understanding and managing PHP projects. This makes it invaluable for auditing and maintaining PHP codebases effectively.

Use case 1: Analyze a directory and print the result

Code:

phploc path/to/directory

Motivation:

Analyzing a PHP directory with PHPLOC helps developers gain quick insights into the project’s size and structure. This can be particularly useful during code reviews or when assessing a project’s initial complexity before diving deeper into its architecture. By providing a concise overview, developers can make informed decisions about code maintenance and optimization processes.

Explanation:

• phploc: The command invoking the PHPLOC utility.
• path/to/directory: The path to the directory containing the PHP code you wish to analyze. This command examines all PHP files within the specified folder, aggregating data about lines of code, files, classes, and more.

Example Output:

Directories                                          10
Files                                               150

Lines of Code (LOC)                              21299
Comment Lines of Code (CLOC)                      1020
Non-Comment Lines of Code (NCLOC)                20279
Logical Lines of Code (LLOC)                     15270

Classes                                            500
Test Classes                                        35
Methods                                           2980
Test Methods                                       124

Use case 2: Include only specific files from a comma-separated list (globs are allowed)

Code:

phploc path/to/directory --names 'path/to/file1,path/to/file2,...'

Motivation:

There are instances when developers are interested in analyzing only specific files within a project, such as recent additions or modifications. Using PHPLOC’s ability to specify files via a comma-separated list allows for focused analysis on parts of the code that are of current interest, thus optimizing the tuning and refinement processes within a development cycle.

Explanation:

• --names '...': This option allows you to specify a list of file paths or patterns using globbing. Only files matching these parts will be included in the analysis.

Example Output:

Analyzed 2 files:

Files                                                 2

Lines of Code (LOC)                                450
Comment Lines of Code (CLOC)                        30
Non-Comment Lines of Code (NCLOC)                  420
Logical Lines of Code (LLOC)                       300

Use case 3: Exclude specific files from a comma-separated list (globs are allowed)

Code:

phploc path/to/directory --names-exclude 'path/to/file1,path/to/file2,...'

Motivation:

There can be scenarios where certain files should be excluded from the analysis, such as auto-generated code or vendor libraries not maintained by the current development team. Using the exclusion feature ensures that only relevant parts of the project are included, leading to a more precise measurement of the real working code.

Explanation:

• --names-exclude '...': This command option lets you exclude specific files from the analysis based on paths or patterns, enhancing the focus on the desired parts of the codebase.

Example Output:

Excluded 2 files:

Files                                               148

Lines of Code (LOC)                              21049
Comment Lines of Code (CLOC)                      1000
Non-Comment Lines of Code (NCLOC)                20049
Logical Lines of Code (LLOC)                     15100

Use case 4: Exclude a specific directory from analysis

Code:

phploc path/to/directory --exclude path/to/exclude_directory

Motivation:

Some directories, such as vendor packages or external libraries, might not be pertinent to the analysis since they contain third-party code. Excluding a directory from the analysis prevents skewed results that could misrepresent the size and complexity of the actual code being developed and maintained internally by the team.

Explanation:

• --exclude path/to/exclude_directory: This option allows you to exclude an entire directory from the analysis, ideal for setting aside irrelevant or non-primary code directories.

Example Output:

Excluded directory: path/to/exclude_directory

Directories                                          8
Files                                               120

Lines of Code (LOC)                              18000

Use case 5: Log the results to a specific CSV file

Code:

phploc path/to/directory --log-csv path/to/file

Motivation:

Logging results to a CSV file allows for persistent storage and further analysis of the data using spreadsheet software or importing into other data analysis tools. This makes comparing historical data or performing more complex data manipulations feasible beyond the command-line interface.

Explanation:

• --log-csv path/to/file: This command parameter specifies the file path to which the CSV output should be written. This enables structured data export for further use.

Example Output:

Content logged to “path/to/file.csv”:

Directories,Files,Lines of Code (LOC),Comment Lines of Code (CLOC),Non-Comment Lines of Code (NCLOC)
10,150,21299,1020,20279

Use case 6: Log the results to a specific XML file

Code:

phploc path/to/directory --log-xml path/to/file

Motivation:

Similar to logging in CSV format, storing data in XML is useful for integration with other tools that require XML input, or for use in environments where XML is the preferred data interchange format. This opens the door to easier automation scripts, or integration with project dashboards that consume XML data.

Explanation:

• --log-xml path/to/file: Specifies the file path where the XML output should be written, facilitating easy sharing and consumption of the data in XML-compatible systems.

Example Output:

Content logged to “path/to/file.xml”:

<?xml version="1.0"?>
<phploc>
    <directories>10</directories>
    <files>150</files>
    <loc>21299</loc>
    <cloc>1020</cloc>
    <ncloc>20279</ncloc>
</phploc>

Use case 7: Count PHPUnit test case classes and test methods

Code:

phploc path/to/directory --count-tests

Motivation:

For projects employing PHPUnit for testing, having a count of test case classes and methods readily available is crucial. This information not only supports understanding of testing coverage but also helps in identifying potential gaps or oversights in the test strategy, encouraging a more robust testing culture within the development team.

Explanation:

• --count-tests: This option adds the capability to count test case classes and methods within the analyzed project directory, allowing for an immediate overview of test implementation.

Example Output:

Test Classes              35
Test Methods             124

Conclusion:

PHPLOC serves as a powerful yet straightforward tool for developers seeking to obtain fast insights into their PHP codebases without the need for complex setup or extensive configuration. From measuring general code metrics to integrating XML or CSV outputs for broader data analysis, PHPLOC’s versatile command options cater to diverse development needs and streamline the maintenance of PHP projects.