Tools Bundle Laravel Package

Getting Started

Treat onboarding as a source-reading exercise first. The package has no adoption footprint, no changelog, and no usage guide, so the repository is the documentation.

1. Read before you require. Clone the repo and inspect composer.json for illuminate/* or symfony/* constraints, the PHP floor, and the autoload block. The -bundle suffix plus the Octave CMS namespace strongly suggests Symfony conventions (*Bundle, service definitions in Resources/config/, a DependencyInjection extension) rather than a Laravel service provider. That single check decides your path:

• If it targets symfony/*, do not composer require it into a Laravel app. Vendor the helper classes you want into app/Support/ with attribution and be done.
• If it declares illuminate/support and an extra.laravel.providers block, it is genuinely a Laravel package and the flow below applies.

2. Install and confirm discovery.

composer require octave/tools-bundle
php artisan package:discover --ansi
php artisan about

If nothing registers, check vendor/octave/tools-bundle/composer.json for the extra.laravel block. A Symfony-style bundle will not auto-discover and must not be forced in.

3. Read the three files that matter, in order:

• The service provider / bundle class — what it registers globally (commands, aliases, helpers, config).
• config/ — every key and its default. Note the merge strategy.
• tests/ — or its absence. The test suite is your only behavioral spec.

4. First use case. Start with the read-only debug utilities: readable dumps and quick inspection are non-destructive, need no wiring, and let you confirm the package boots and behaves before you touch string/array helpers that domain code might depend on. Wire one call into a throwaway Tinker session or a local-only route. Only after that do you let helper calls into application code.

5. Name an owner. With zero upstream dependents, the person who reads the source is the maintainer. Record that before the first merge.

Implementation Patterns

Thin adapter over the helpers. Do not call octave/tools-bundle functions directly from controllers, models, or jobs. Wrap each one you actually use behind your own interface or static facade in app/Support/:

namespace App\Support;

class Str
{
    // delegates now, replaces later — callers never see the package
    public static function slugify(string $value): string
    {
        return \Octave\ToolsBundle\Support\Str::slugify($value);
    }
}

This is the whole adoption pattern. It makes vendor-vs-fork-vs-skip a later decision that costs a file edit instead of a refactor, and it keeps the blast radius of a behavioral change inside one class.

Debug utilities stay dev-only. Gate every dump/inspect call behind an explicit environment check or a config flag owned by your app, not the package. These are the helpers most likely to be re-run under Octave and the ones whose output format you care least about, so they are the highest-value, lowest-risk thing to adopt.

Config publish, then diff. Run the vendor publish once and commit the published config. Diff it against the package default so upgrade-time config drift is visible in review rather than at runtime. If the package merges config aggressively, set your keys explicitly and assume the package's defaults are placeholders.

Test the surface you use, not the package. Write a small contract test in your own suite covering each adopted helper's input/output for the cases your app relies on. You are not validating the package's quality — you are freezing the behavior you depend on so an unpinned composer update fails your CI instead of your users.

Vendor for anything small. If the source is a few hundred lines, copy the classes you need into app/Support with a license header and delete the dependency. In practice this is usually the right call for a tooling bundle: you keep the utility and shed the governance risk.

Gotchas and Tips

• The -bundle suffix is the trap. It is a Symfony convention. Confirm the framework target from composer.json before anything else; a Laravel-focused description and a Symfony package can coexist and will waste your afternoon.
• Auto-discovery may silently not run. A Symfony bundle has no extra.laravel.providers, so package:discover reports success while registering nothing. Never infer registration from a clean install.
• Global container side effects. Read the service definitions for what loads at boot — aliases, commands, middleware, helper functions. A "lightweight utilities" bundle that pushes a debugbar-style middleware onto every request is not lightweight, and it is the one way tooling code reaches production.
• No semver guarantees. At zero dependents there is no pressure to tag or keep tags stable. Pin to an exact version or a commit SHA in composer.json; do not accept ^1.0-style ranges or dev-main.
• Laravel major-version churn. Internal hooks age out every 12–18 months. Put a review line on the next Laravel upgrade checklist now, and budget a day or two to validate.
• Debug output leaks. Readable dumps that var_dump request state can print secrets in non-production logs. Grep for the package's dump helper before shipping and add it to your "no direct call in app code" rule.
• Config collisions. If the package publishes aggressively, its keys can shadow app-level config. Namespace your own keys and never rely on the package's defaults surviving an update.
• Supply-chain hygiene. A dormant vendor namespace with no maintainers is a takeover vector. Pin to a commit SHA you have reviewed, or eliminate the dependency by vendoring — the latter removes the risk entirely and is why it is the default recommendation for a package this small.
• Extension points are your escape hatch. The description advertises an "extensible design." If you adopt, exercise the intended extension point early — adding one custom helper — so you discover whether extending is clean or whether you are expected to patch vendor code.
• No SLA, no triage history. Any incident routes to whoever last read the source. Keep the tools off the production path and out of request handling so that person is never paged.