Download the PHP package sl5net/preg-contentfinder without Composer

PregContentFinder

A powerful and robust PHP library for finding, extracting, and transforming content within text based on regular expression (PCRE) delimiters, featuring advanced support for nested structures, custom callback processing, and intelligent delimiter handling.

A Legacy of Stability: The fundamental recursive parsing logic and the intelligent handling of delimiter conflicts have been stable and functional since its early years (around 2002-2003, likely PHP 4). Subsequent updates primarily focused on adapting to new PHP versions (like PHP 5.6). This latest modernization brings the proven core engine to PHP 8.1+, integrating it with Composer and modern PHP standards.

It excels where simple string functions or basic regex fall short, particularly with nested structures and context-dependent transformations.

Key Features

• Delimiter-Based Searching: Use strings or full PCRE regular expressions for start and end delimiters.
• Intelligent Nested Structure Handling: Reliably finds content within correctly balanced and nested delimiter pairs, even when the content itself contains delimiter characters. You often don't need to worry about manually escaping delimiter characters within your content.
• Recursive Processing: Apply transformations recursively through nested structures using getContent_user_func_recursive.
• Custom Callback Functions: Pass PHP callables to dynamically process and transform the content found between delimiters, receiving context like nesting depth and match details.
• Flexible Search Modes:
  • lazyWhiteSpace: Treats delimiters as literal strings, quoting them and making whitespace flexible.
  • dontTouchThis: Treats delimiters as raw PCRE patterns provided by the user.
  • use_BackReference_IfExists_()$1${1}: Allows the end delimiter's regex to use backreferences from the start delimiter's match (e.g., for matching <div>...</div>).
• Content Access: Easily retrieve content between, before, or after matched delimiters for the current match.
• Modernized: PHP 8.1+ compatible, PSR-4 compliant, available via Composer.
• Well-Tested: Backed by ~100 unit tests ensuring core functionality and robustness.

Why PregContentFinder?

Use this library when you need to:

• Parse and transform custom template languages or markup (like BBCode).
• Reliably extract data from semi-structured text files with potentially nested blocks, even if those blocks contain delimiter characters.
• Perform context-aware text transformations using callbacks based on nesting or content.
• Analyze or refactor code structures based on block delimiters.
• Implement interpreters for simple, domain-specific languages.

Its unique combination of features, especially the robust handling of nested structures and internal management of delimiter conflicts, makes it a powerful tool for complex text processing tasks.

Installation

The recommended way to install PregContentFinder is via Composer:

Basic Usage

Advanced Examples

1. Transforming Nested Structures (Simple Replacement)

Input:

Goal: Change { to [ and } to ].

PHP Code:

(The simple { to [ example is a bit tricky to show concisely without knowing the exact callback logic used to produce that specific output. The power is that the callback can do this.)

2. Code Indentation / Pretty-Printing (Conceptual)

Input:

Goal: Indent based on nesting.

PHP (Conceptual Callback Logic):

Use Cases

PregContentFinder is well-suited for:

• Parsing and transforming custom template languages or markup (like BBCode).
• Extracting data from semi-structured text files with nested blocks.
• Code analysis and transformation (e.g., pretty-printing, refactoring simple patterns).
• Implementing interpreters for simple, domain-specific languages.
• Any task requiring robust identification and manipulation of hierarchically structured text.

Development Workflow & Management Script

For a streamlined development workflow, including building Docker images for different PHP versions, running tests, and managing Docker resources, a dedicated helper script is available.

This script automates common tasks and helps in maintaining a clean Docker environment.

You can find this management script in the SL5_some_favorite_scripts repository:

➡️ PCF Management Script ⬅️ (Link directly to the script file)

Or browse the directory containing other useful shell scripts: ➡️ SL5 Favorite Shell Scripts (Link to the sh directory)

Key features of the script:

• Automatically detects the target PHP version from the Dockerfile or Git context.
• Builds Docker images spezifisch for the detected PHP version.
• Runs PHPUnit tests within the Docker environment.
• Provides actions to clean up Docker resources (full system prune or just build cache).
• Displays Docker disk usage.
• Includes a detailed help screen with usage instructions and tips for setting up shell aliases/functions for easier access.

It's recommended to place this script outside the SL5_preg_contentFinder project directory and call it using a relative path or a shell alias/function as described in its help output.

License

PregContentFinder is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues. (Consider adding a CONTRIBUTING.md file if you have specific guidelines).