Php Construct Normalize Laravel Package

Getting Started

Install via Composer and pin the version:

composer require leovie/php-construct-normalize:^2.0

Where to look first. The repository is small; read the following in this order:

1. README.md — expect only a short example, not a full API reference.
2. src/ — the normalizer classes/functions are the entire public surface.
3. tests/ — the test suite is the most reliable documentation of what "normal" means for each construct. Fixture-based tests will show exact input/output pairs.

First use case. The realistic reason to reach for this package is normalizing PHP source or AST fragments into a canonical form so you can compare, diff, or generate them consistently. A minimal sanity check:

require 'vendor/autoload.php';

// Confirm the API from src/ before assuming this shape
$normalized = \LeoVie\PhpConstructNormalize\Normalizer::normalize($phpSnippet);

var_dump($normalized === $expectedCanonical);

If the call shape does not match, open the source and copy the signature from the public class. There is no vendor documentation to fall back on.

Implementation Patterns

Because the package has near-zero adoption, treat it as a building block in your own pipeline rather than a drop-in tool.

Canonicalization for comparison/diffing. Wrap the normalizer in a helper that takes two PHP snippets and returns whether they are semantically equivalent after normalization. This is the highest-value pattern: it lets you assert equivalence in tests without brittle string matching.

function php_equivalent(string $a, string $b): bool
{
    $normalizer = new Normalizer();
    return $normalizer->normalize($a) === $normalizer->normalize($b);
}

Code generation pipeline. If you generate PHP from templates or builders, run the output through the normalizer before writing to disk. This gives deterministic formatting regardless of how the generator assembles fragments — useful when goldens are checked into version control.

$generated = $builder->getCode();
file_put_contents($path, $normalizer->normalize($generated));

Preprocessing for static analysis. If you feed code into a downstream AST diff, linter, or hash-based cache, normalize first so that cosmetic differences (quoting, whitespace, equivalent constructs) don't defeat your comparison.

$hash = md5($normalizer->normalize($source));

Fixture-based development. Build a tests/Fixtures directory in your project mirroring the patterns you care about. Every construct you depend on should have an input→output pair pinned. When the package silently misses a construct, you catch it there rather than in production.

Adapter around the normalizer. Don't call the package directly from many places. Add a thin PhpNormalizer service in your app that delegates to the library. If you later swap it for nikic/php-parser plus pretty-printer (a much better-maintained route), you change one class.

Gotchas and Tips

• Maintenance is low-volume but not dead. v2.0.2 is a Composer bookkeeping patch, not a feature release; the API is unchanged from 2.0.1 and nothing is deprecated. Still treat the package as low-velocity: constrain with "leovie/php-construct-normalize": "^2.0", read the diff of any 2.x bump (they are short), and assume bug fixes for construct edge cases are not coming quickly.
• Good news from v2.0.2: roave/security-advisories is now dev-only. On earlier 2.x it sat in require, which meant installing this package dragged a security-advisories constraint into your runtime dependency graph — a classic source of composer update conflicts when your app pins its own version. If you were on 2.0.1 and fighting resolver errors, upgrading to 2.0.2 is a cheap win. Verify with composer why roave/security-advisories after upgrading; it should no longer appear as a runtime requirement.
• "Normalize" is ambiguous. The package covers some PHP constructs, not all. Before relying on it, write a probe script that runs dozens of snippets (arrays, closures, match expressions, nullsafe calls, enums, attributes) through it and inspect the output. Anything unchanged is a construct it does not handle. Note the patch release touched no source files, so whatever your probe said on 2.0.1 still holds.
• Newer PHP syntax may pass through unchanged. The normalizer's construct coverage predates PHP 8.2+/8.3+ features (readonly classes, typed constants, DNF types). Do not assume it will normalize or even parse them correctly — guard with a try/catch and log failures.
• Check composer.json require for the PHP floor. If it targets PHP 7.x, you may hit deprecation notices under 8.3. Run with error_reporting(E_ALL) once to surface them.
• No documentation = read src/. Do not trust examples from blog posts; the API surface is whatever the classes declare. Copy signatures directly.
• Extension points are limited. If the normalizer is a final class or exposes no interface, you cannot extend it cleanly. Prefer composition (wrap it) over inheritance, and keep the adapter boundary.
• Debugging failures. When normalization produces unexpected output, first check whether the input is valid PHP (run php -l). The normalizer likely assumes valid input and may throw or silently return the input unchanged on failure. Add explicit validation before the call.
• Whitespace vs. semantic normalization. Confirm whether the tool canonicalizes formatting (whitespace, indentation) or constructs (e.g., array() → []). Conflating these leads to surprising test failures. Pin expected outputs so the behavior is documented in your codebase.