Common Laravel Package

Getting Started

Start by verifying you can even install it. There is no Packagist listing, no changelog, and no README-derived API reference in the available material, so the first ten minutes are a provenance check, not an integration:

1. Open composer.json on the GitLab repo. Read require (especially php and symfony/*), autoload (PSR-4 namespace roots — this tells you the real entry points), and license.
2. Check for a LICENSE file at the repo root. Anything without one is all-rights-reserved by default, which stops you before step 3.
3. Check git tag / the tags page. No tags means no semver contract; you will pin a commit SHA if you proceed at all.
4. Clone and list src/. Classify every file into (a) pure PHP (helpers, DTOs, enums, value objects), (b) Symfony-coupled (bundles, compiler passes, services.yaml, DependencyInjection/), (c) non-code (CI configs, editor settings, phpstan/php-cs-fixer rulesets).
5. Dry-run the resolve in a throwaway branch: add a vcs (or path) repository entry and run composer update --dry-run --with-dependencies. This surfaces Symfony-vs-illuminate/* constraint conflicts cheaply, before you write a line of glue.

Where to look first. src/ and composer.json are the entire surface area. Skip tests/ until you've decided to adopt — there is no signal that tests exist or run, so treat them as documentation of intended behavior rather than a safety net.

The realistic first use case is a one-to-two-day discovery spike, not a feature. Note that this is a Symfony shared bundle ("Common files for Krystal Symfony Projects"); if you are on Laravel, nothing in category (b) boots, nothing in category (c) applies, and category (a) is unverified. The first productive outcome is an inventory: "these N files are pure PHP and useful; everything else is inert for us." That inventory is what you take to the build-vs-vendor decision.

If you are genuinely inside Krystal on a Symfony app, the adoption path is conventional: require the bundle, register it in config/bundles.php, and look for a DependencyInjection/Configuration.php to see what's configurable. There is no published documentation, so the bundle's Configuration node tree and the traits' method signatures are the documentation — read them in that order.

Implementation Patterns

Pattern 1 — consume only the leaf utilities. This is the only runtime-usage pattern worth considering from outside Krystal. Enumerate the pure-PHP classes (helpers for strings/arrays/env handling per the package description), confirm each has no Symfony container awareness, and either (a) require the package constrained to a commit SHA, or better (b) copy those specific files into your own namespace with attribution and a license header. Option (b) costs an hour and eliminates the dependency entirely. Write your own unit tests against the copied code — you will be the only person who ever has.

Pattern 2 — traits as a consistency layer. If the package ships traits intended to keep package structure uniform across a family of packages, the value is in the shape: consistent composer.json metadata, consistent service-provider/base-class skeletons, consistent config-merge conventions. Read two or three of these traits side by side and you will see the team's internal package conventions in about fifteen minutes. That is the highest-yield reading in the repo, and it transfers to Laravel almost unchanged in spirit — a BaseServiceProvider with mergeConfigFrom/publishes, a HasPackageConfig trait, a standard test base case.

Pattern 3 — reference implementation for your own shared foundation. The productive workflow is: read the repo, extract 3–5 ideas, delete the clone. Concretely, decide what your internal shared package should own (DTOs, base test case, phpstan/php-cs-fixer rulesets, CI templates, health-check endpoint), and mirror the factoring they chose — one package, one purpose, framework-friendly, minimal dependencies. Do not import their Symfony bootstrapping semantics into a Laravel service provider; the container lifecycles are not equivalent.

Pattern 4 — scaffolding, not dependency. If discovery reveals this is closer to a project skeleton or a config/asset repo than a Composer library, the correct integration is git clone into a scratch directory and copy the config files you want. No composer.json entry, no trust boundary extension, no CI credential surface.

Anti-pattern to avoid. Do not build an adapter layer to make Symfony-coupled base classes work under Laravel. You would be writing glue code to consume glue code — the adapter becomes your most fragile, least-tested file, and it is maintained by nobody upstream.

Integration tip for anything that does proceed: isolate it behind your own interface even if you don't wrap it. A single app/Support/ facade over the handful of helpers you actually use means the eventual rip-out is a one-file change instead of a codebase-wide grep.

Gotchas and Tips

The license is the hard stop. No visible LICENSE file means all-rights-reserved. "Publicly visible on GitLab" is not a license grant. Verify before any code enters your tree — including copied files, which is the failure mode people miss.

Symfony constraints collide with Laravel. A package pinning Symfony 4.x/5.x components will hard-conflict with Laravel 10/11's illuminate/* requirements in composer update. This is not resolvable without forking and relaxing constraints. Run the --dry-run probe before committing to anything; a failed resolve is the cheapest possible "no."

No tags means no BC contract. If you take a VCS dependency, pin an exact commit SHA — never a branch. Branch constraints silently pull untagged upstream commits, which is how "it worked yesterday" happens. Mirror the repo internally if CI depends on it.

Private GitLab auth is a new failure mode. A vcs repository entry means your CI inherits Krystal's credential and availability surface. Expect intermittent, slow-to-diagnose build failures when tokens expire — and note that a shared-foundation package is exactly the kind of dependency nobody has on their critical-path radar when it breaks.

"Common" packages encode invisible assumptions. Expect hardcoded env var names, filesystem layout expectations, log formats, and config keys that surface only at runtime. Grep the source for getenv, $_ENV, env(, and absolute paths before wiring it in.

Check for transitive private dependencies. A Krystal-internal package may require other Krystal-internal packages, turning one dependency decision into a chain. Read the full require block, not just the top level.

Base classes are a poor extension point here. Traits you can override cleanly; a base class from an unmaintained package is fragile inheritance — you inherit every future non-change too. Prefer composition: hold an instance, don't extend it.

Debugging without a changelog. There is no release history to bisect against. Keep a short note of the commit SHA you vendored and a one-paragraph summary of what you took from it; that note is your entire upgrade path.

PHP version floor. Older internal packages frequently pin ^7.4/^8.0, which signals the code predates enums, readonly properties, and modern typing. Check ext-* requirements against your runtime images too.

Budget the exit, not just the entry. Two to four hours per quarter for drift review, or near-zero if you vendor and sever the link. Given zero stars and zero dependents, vendoring is the default and composer require needs a specific justification — "it saved us writing forty lines of array helpers" is not one.