Awesome
code-snippets
<p align="center"> <img src="https://img.shields.io/github/v/release/permafrost-dev/code-snippets.svg?sort=semver&logo=github" alt="Package Version"> <img src="https://img.shields.io/github/license/permafrost-dev/code-snippets.svg?logo=opensourceinitiative&" alt="license"> <img src="https://github.com/permafrost-dev/code-snippets/actions/workflows/run-tests.yml/badge.svg?branch=main&" alt="Test Run Status"> <img src="https://codecov.io/gh/permafrost-dev/code-snippets/branch/main/graph/badge.svg" alt="code coverage"> </p>Easily create and work with code snippets from source code files of any type in PHP.
The original code this package is based on was borrowed from the spatie/backtrace
package.
Installation
You can install the package via composer:
composer require permafrost-dev/code-snippets
Usage
Note: Although the examples here reference php files, any file type can be used when creating a CodeSnippet
.
Creating a snippet
Use the surroundingLine($num)
method to select the "target" line, which will be returned as the middle line of the snippet:
use Permafrost\CodeSnippets\CodeSnippet;
$snippet = (new CodeSnippet())
->surroundingLine(4)
->snippetLineCount(6)
->fromFile('/path/to/a/file.php');
Use the surroundingLines($first, $last)
method to select a range of "target" lines, which will be returned as the middle lines of the snippet:
$snippet = (new CodeSnippet())
->surroundingLines(4, 7)
->snippetLineCount(6)
->fromFile('/path/to/a/file.php');
Use the linesBefore()
and linesAfter()
methods to specify the number of context lines to display before and after the "target" lines:
// the "target" line isn't displayed in the middle, but as the second line
$snippet = (new CodeSnippet())
->surroundingLine(4)
->linesBefore(1)
->linesAfter(3)
->fromFile('/path/to/a/file.php');
Getting the snippet contents
The getLines()
method returns an array of SnippetLine
instances. The keys of the resulting array are the line numbers.
The SnippetLine
instances may be cast to strings to display the value. When working with SnippetLine
instances, use isSelected()
to determine if the line was selected using either the surroundingLine()
or surroundingLines()
method on the CodeSnippet
instance.
To get the value of a SnippetLine
, use the value()
method or cast the object to a string.
$snippet = (new CodeSnippet())
->surroundingLine(4)
->snippetLineCount(5)
->fromFile('/path/to/a/file.php');
foreach($snippet->getLines() as $lineNum => $line) {
$prefix = $line->isSelected() ? ' * ' : ' ';
echo $prefix . $line->lineNumber() . ' - ' . $line->value() . PHP_EOL;
}
Snippet line count
To determine the number of lines in the snippet, use the getSnippetLineCount()
method:
$snippet = (new CodeSnippet())
->surroundingLines(4, 7)
->linesBefore(3)
->linesAfter(3)
->fromFile('/path/to/a/file.php');
echo "Snippet line count: " . $snippet->getSnippetLineCount() . PHP_EOL;
You can also use count()
on the result of the getLines()
method:
$snippet = (new CodeSnippet())
->surroundingLines(4, 7)
->linesBefore(3)
->linesAfter(3)
->fromFile('/path/to/a/file.php');
echo "Snippet line count: " . count($snippet->getLines()) . PHP_EOL;
To return an array containing the line numbers for the snippet, use getLineNumbers()
:
print_r($snippet->getLineNumbers());
Returning the snippet as a string
Return the contents of the snippet as as string using the toString()
method or by casting the snippet to a string directly:
$snippet = (new CodeSnippet())
->surroundingLines(4, 7)
->linesBefore(3)
->linesAfter(3)
->fromFile('/path/to/a/file.php');
echo "Snippet: \n" . $snippet->toString() . PHP_EOL;
Testing
./vendor/bin/phpunit
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.