code-snippets
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.
5 Feb 24, 2022
245 Dec 18, 2022
7 Nov 29, 2022
8 Jun 8, 2023
30 Dec 6, 2022
294 Jan 5, 2023
4 Jun 22, 2022
19 Dec 27, 2021
2.3k Jan 7, 2023
303 Dec 20, 2022
151 Dec 27, 2022
255 Nov 16, 2022
2 Dec 30, 2022
71 Nov 15, 2022
786 Dec 30, 2022
0 Mar 20, 2022
27 Nov 1, 2022
9 Dec 30, 2021