README

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.

permafrost-dev / code-snippets

Maintainers

Details