Vocal Laravel Package

Getting Started

Vocal 2.0.0 is a ground-up rewrite, so treat it as a new package rather than a version bump. The 1.0.x line is what you want on Laravel 4.x or 5.0; 2.x targets Laravel 5 and drops PHP 5.3.

1. Confirm your platform before anything else: Laravel 5.x and PHP 5.4+. If you are still on Laravel 4, stay on 1.0.x — 2.x will not run.
2. composer require sjdaws/vocal:^2.0 in a branch, not on master.
3. Register the service provider (and any facade alias) manually in config/app.php — this predates package auto-discovery, so nothing is wired up for you.
4. Publish and diff the config: php artisan vendor:publish then compare the new config file against whatever you had, rather than assuming the keys are identical.
5. Read the readme before writing a single call. The release notes explicitly say 2.x has the same method names as 1.x but different parameters. That is the entire migration surface, and the readme is the only place it is documented.

The best first use case is not "upgrade the app" — it is picking one isolated call site, porting it by hand against the readme's signatures, and getting a test green. That gives you a template for the remaining call sites and tells you how much of the rewrite actually leaks out of the public API.

Implementation Patterns

Map old signatures to new ones before touching code. Build a two-column table in the PR description: old call (with positional args annotated) → new call. Do this by reading the readme, not by running the code. Because method names are unchanged, mistakes here do not throw — they silently pass the wrong value into the wrong slot.

Prefer named arguments (or an explicit array) at the call site. The parameters changed once; assume they can change again. Named arguments turn a future silent breakage into a hard error.

Wrap the package behind a thin application-level adapter. A single class or two that owns every Vocal call means the next rewrite is a one-file change instead of a grep across the codebase. This is cheap insurance specifically because 2.0 proved the package is willing to change parameter shapes.

Keep configuration in config/ and out of code. Use env-driven values for anything environment-specific so staging and production do not need separate call-site logic.

Test at your adapter boundary, not against package internals. The rewrite means internal classes and namespaces almost certainly moved even where the public facade stayed stable. Assertions written against internals will break on every minor release; assertions on your adapter's behavior will survive.

Pin the constraint. Use ^2.0 deliberately — and if you have any long-lived 1.x services, pin those to ^1.0 explicitly. Do not let a floating constraint drag an old service into a rewrite.

Gotchas and Tips

• Same names, different parameters is the dangerous kind of breaking change. There is no deprecation layer and no compatibility shim here. Existing 1.x calls will very likely still execute without a fatal error and simply produce wrong results. Add or strengthen tests around every call site before you swap the version.
• The changelog gives you no per-method migration table. "Parameters have changed" is the whole story. The readme is the source of truth; if a method you rely on is under-documented, read the source rather than guessing the order.
• Do not upgrade across the Laravel 4 boundary. 2.x is Laravel 5 only. If any part of the estate is on Laravel 4, it needs to stay on 1.0.x — which means you now maintain two versions in parallel.
• Update your CI matrix for the PHP floor. Dropping 5.3 is a build-configuration change as much as a code change; a stale matrix will hide or invent failures.
• Do not reach into internals. A "complete rewrite to simplify methods" means classes, namespaces, and possibly container bindings moved. Anything you resolved out of the container by class name or extended directly should be re-verified, not assumed.
• Re-publish and diff config, don't overwrite. vendor:publish will clobber a customised config file. Copy the published file aside and diff it against yours so new or renamed keys are visible.
• Debugging tip: if a ported call returns something plausible but wrong, check argument order first — before you check the package's logic. Given the release shape, ordering is the overwhelmingly likely culprit.
• Extension point: the adapter from the patterns section is also your escape hatch. If a 2.x behavior regresses something you depended on, you can reimplement that one method in the adapter without forking the package.