Introduction to the Lines CLI Tool
Lines is a Command Line Interface (CLI) tool created to provide a quick and straightforward measure of the size of PHP projects. Its simplicity and flexibility make it a valuable asset for developers who want to gain insights into their codebase without delving into complex details.
Key Features
Universal Installation
Lines is designed to run almost anywhere, with compatibility starting from PHP 7.2 onwards. It boasts zero dependencies, allowing it to function across various environments, regardless of the other PHP tools or frameworks you might be using, such as PHPUnit 6 or Symfony 3.
Project Size Overview
The primary purpose of Lines is to offer a rapid overview of your project's size. It counts lines of code without getting bogged down by intricate data or complex analytics. For more detailed code analysis, other tools like PHPStan would be more appropriate.
JSON Output
The tool provides an easy-to-use JSON output option, enabling further processing or integration with other tools and workflows.
Installation Guide
Given its lightweight nature, installing Lines is straightforward. It is available as a Composer package, and you can include it as a development dependency in your project with this command:
composer require tomasvotruba/lines --dev
How to Use Lines
Using Lines is simple. The primary command to measure your source directory is:
vendor/bin/lines measure src
For a more concise output, you can use the --short option:
vendor/bin/lines measure src --short
If JSON data is preferred, append the --json flag:
vendor/bin/lines measure src --json
These options can be combined for specific needs, such as generating short JSON output suitable for inclusion in blog posts or tweets:
vendor/bin/lines measure src --short --json
If you are interested in identifying the top 10 longest files in your project, the --longest option can be employed:
vendor/bin/lines measure src --longest
This will list files with their respective line counts, offering an immediate insight into the heftiest portions of your codebase.
Understand the Output
Lines provides a range of outputs. Here's what you can expect:
For text output, information is categorized into sections like filesystem stats, lines of code, code structure data, and method access and visibility statistics. For instance:
- Filesystem: Number of directories and files.
- Lines of Code: Count of code lines versus comments, along with relative percentages.
- Structure: Breakdown of namespaces, classes, interfaces, traits, and functions.
- Methods Access & Visibility: Insights into static versus non-static methods, and public, private, and protected access levels.
Alternatively, the JSON format provides the same data in a structured format, ideal for further processing or automation purposes.
Handling Vendor Files
By default, Lines ignores vendor directories where third-party libraries reside, to prevent skewed results due to large volumes of external code. However, if an analysis of vendor files is necessary, the --allow-vendor option allows for their inclusion in the measurement:
vendor/bin/lines measure vendor/rector/rector --allow-vendor
This feature ensures Lines focuses on your code, but remains versatile for comprehensive analysis when required.
In summary, Lines is a versatile, dependency-free tool that simplifies the process of understanding PHP project sizes. It’s an excellent first step for developers who want a quick and easy read on their codebase's footprint.