Common Laravel Package

Getting Started

bolt/common is a small PHP utility library extracted from Bolt CMS — no service provider, no auto-registered config, no runtime hooks. It is a leaf dependency: PSR-4 namespace Bolt\Common\, plain classes you use and call. That shapes everything about how you adopt it.

Install and confirm you actually need it. It is almost always already present transitively via bolt/core (or an older Bolt 4 bolt/* stack). Check before adding it explicitly:

composer why bolt/common
composer show bolt/common

If you are on a Bolt-based app, do not add a second constraint — align with whatever bolt/core already requires, otherwise Composer will happily install two majors and you get duplicate-class/Cannot redeclare class failures at autoload time.

Look here first, in this order:

1. vendor/bolt/common/composer.json — the require block tells you the real floor (PHP and Symfony version). Last release was 2021-11-08, so expect PHP 7.4/8.0-era constraints; that is your first compatibility gate.
2. vendor/bolt/common/src/ — enumerate the surface in one shot rather than reading the README:

   find vendor/bolt/common/src -name '*.php' | sed 's|vendor/bolt/common/src/||'
   

3. vendor/bolt/common/tests/ — if present, this is the de facto documentation. Assertion inputs/outputs for helper functions are worth more than any prose.

First use case: pick the one helper you were about to hand-roll — version comparison, string/path normalisation, config array merging — and call it from a throwaway script before wiring it in:

require 'vendor/autoload.php';
var_dump(\Bolt\Common\...::class); // confirm the class resolves

The win is only real if it replaces code you'd otherwise maintain. Read the method body of anything you plan to depend on; these are small classes and a two-minute read is cheaper than a production surprise.

Implementation Patterns

Treat the package as internal utility code you happen to get via Composer, not as a framework you build on.

Call helpers at the edges, not in your domain. The natural homes are Twig extensions, console commands, formatters, and import/export adapters — the places where you already accept "whatever the CMS does" formatting. Keeping calls out of your entities and services means a fork or replacement later is a one-file change.

Wrap statics behind your own service. Much of what a package like this exposes is static helpers, which are untestable and unmockable at the call site. Define a thin interface in your app and delegate:

interface Slugs { public function slugify(string $text): string; }

final class BoltSlugs implements Slugs
{
    public function slugify(string $text): string
    {
        return \Bolt\Common\...::slugify($text); // single call site
    }
}

Now the dependency is swappable, and your tests mock Slugs, not the vendor.

Version and capability checks. If you are writing an extension that must run against several Bolt majors, this is where the package earns its keep — comparison and normalisation of version strings is exactly the kind of code you should not reimplement. Centralise it:

if (Version::compare($appVersion, '4.1.0') >= 0) { /* new API */ }

Config handling. If the package offers array/ArrayAccess config utilities, use them to normalise incoming config (YAML, env, extension defaults) at your boundary, then hand your own typed config object deeper into the app. Don't let vendor config shapes leak inward.

Testing pattern. Because the logic is pure, test your wrapper's behaviour and add one smoke test per vendor method you rely on. That smoke test is your early-warning system if you ever bump the dependency.

Composer hygiene. Pin to the exact version your Bolt stack resolves, commit composer.lock, and if you must patch behaviour, use cweagans/composer-patches with a patch file rather than editing vendor/. Keep the patch small enough to re-apply after a bump.

Gotchas and Tips

It is stale — plan accordingly. A single release in late 2021 and 18 stars means no roadmap, no PHP 8.2/8.3 deprecation fixes, and no security response. Vendor it or fork it deliberately; do not treat "upstream will fix it" as a mitigation. Check composer outdated and expect it to be flagged.

Version constraints are coarse. Small packages in this position often ship 0.x or loose constraints, so a composer update can shift behaviour silently. Pin exactly and read the diff on every bump — the classes are small enough that a full read is minutes.

Duplicate classes are the most likely failure. If two Bolt packages require different majors, you get confusing Cannot redeclare or "method not found" errors that look like your bug. Diagnose with:

composer why bolt/common
composer dump-autoload -o
php -r 'require "vendor/autoload.php"; $r = new ReflectionClass("Bolt\\Common\\..."); echo $r->getFileName();'

The getFileName() output tells you which copy is actually loaded — always confirm before debugging your own code.

Static helpers resist mocking. If you find yourself needing Mockery::mock() on a vendor static, that is a signal to add the wrapper described above rather than to reach for alias mocks.

Exceptions may be Bolt-flavoured. Error types from a CMS-derived library sometimes assume a booted application (container, request context). Catch narrowly and convert to your own exception type at the wrapper boundary so callers never see vendor internals.

Extension points are composition, not plugins. There is no event dispatcher here. Subclass or compose, and keep additions in your own namespace — subclassing vendor internals couples you to their private structure and makes patching harder.

Debugging shortcuts. For a package this size, grep -rn "function " vendor/bolt/common/src is faster than any documentation, and git log/CHANGELOG.md in the vendor dir (if shipped) tells you what changed between the release you have and the one you are considering.

License is MIT — forking, vendoring, and shipping modified copies are all fine. Keep the copyright notice, and record the fork point in your changelog.