Php Tools Laravel Package

Getting Started

composer require jacklam/php-tools

Before writing a single line against it, do three things in order:

1. Read composer.json in the package. Confirm the PHP constraint (require.php) is compatible with your runtime (Laravel 10/11 → PHP 8.1/8.2/8.3), and check extra.laravel.providers / extra.laravel.aliases. A "useful tools" library of this size almost certainly ships no service provider and no facade — it is a PSR-4 dump of static helper classes. If extra.laravel is absent, there is nothing to register; just use the classes.
2. List the namespace. ls vendor/jacklam/php-tools/src and skim README.md. At ~4 stars and 0 dependents, the entire source is likely a few hundred lines — read all of it. This is a 10-minute investment that replaces all guesswork below.
3. Smoke-test in Tinker before adopting:

php artisan tinker
>>> class_exists(\JackLam\PhpTools\...::class)

First use case: treat it as a drop-in replacement for the ad-hoc functions accumulating in app/Support/helpers.php — array reshaping, string case conversion, number formatting, safe type coercion. The value proposition is identical to Illuminate\Support\Str/Arr, so the realistic adoption path is: find one helper in your codebase that duplicates a function in this package, swap it, run the test suite, and decide whether to expand usage. If your codebase has no such duplication, do not adopt this package — a 4-star, zero-dependent dependency is a liability unless it removes code you already wrote.

Pin the version exactly ("jacklam/php-tools": "1.0.3") and commit composer.lock, given the lack of maintainer track record.

Implementation Patterns

Adapter wrapper (recommended default). Never call package statics from controllers, jobs, or Blade. Put a thin seam in front of it so you can swap or vendor the code later without a grep-and-replace across the app:

namespace App\Support;

final class Tools
{
    public static function toSnake(string $value): string
    {
        return \JackLam\PhpTools\Str::toSnake($value);
    }
}

This costs one file and gives you a mockable boundary — static package helpers are otherwise untestable.

Vendoring for high-traffic paths. MIT-licensed and small means you can legitimately copy the two or three functions you actually use into app/Support/ with an attribution comment, then composer remove the package. This is the correct call when you use <20% of the API and the project has any production lifespan; you eliminate supply-chain and abandonment risk entirely.

Service-layer usage for data cleanup. The natural fit for a helper library is one-off work: importers, seeders, CSV normalization, legacy migration scripts, Artisan commands under app/Console/Commands. Use it there first — these paths are low-blast-radius, and a bug in a seeder is a rerun, not an incident.

Blade. If you need formatting in views, expose it through a Blade directive or a view composer rather than calling the package namespace inline:

Blade::directive('slug', fn ($expr) => "<?php echo e(\App\Support\Tools::toSnake($expr)); ?>");

Test strategy. Unit-test your App\Support\Tools wrapper with representative inputs, including null, empty string, and multibyte strings. Do not write tests against the vendor namespace — they will be discarded the moment you vendor or replace the package, and they lock in behavior you do not control.

Composer hygiene. Run composer dump-autoload -o after install and verify the autoload type. If the package uses files autoload (global function definitions), it loads on every request — check for that in composer.json before assuming it is free.

Gotchas and Tips

Global function collisions. The most common failure mode of small "tools" libraries is a files-autoloaded helpers.php defining str_contains, array_get, or similar. On PHP 8.x these are engine builtins and redeclaration is a fatal error — unless the package wraps each in if (!function_exists(...)). Grep for function in vendor/jacklam/php-tools on day one. Laravel also defines a large global helper surface; collisions here take down the whole app, not one request.

No maintainer SLA. 4 stars / 0 dependents / score ~0.05 means no security review, no issue triage, no upgrade path. Check the last commit date against your PHP version floor. If the package targets PHP 7.x with no ^8.0 in the constraint, composer require will either fail or force --ignore-platform-reqs — the latter is a red flag, not a workaround.

Static state and mocking. If any class caches internally (a static $instances array or memoized lookups), tests will leak state between cases. Reset in tearDown or avoid those classes entirely.

Error handling is undocumented. Small libraries frequently return null or false on bad input instead of throwing. Establish the contract yourself with a short Tinker matrix — pass null, '', [], 0, and a unicode string to each function you adopt, and record what comes back. Wrap anything that can silently produce null before it reaches a database column.

Config and publishing. If there is a config/ directory, check for a service provider exposing vendor:publish --tag=.... Absent a provider, config files are dead weight — ignore them.

Extension points are limited. With static helpers there is no DI, no interface, no decorator. Your only real extension point is the adapter wrapper (to swap behavior) or a fork (to fix bugs). If you need a bug fixed upstream, expect to maintain the fork; plan for "repositories": [{"type": "vcs", ...}] in composer.json from the start rather than being surprised later.

Debugging. Class not found after install is almost always a stale autoloader — run composer dump-autoload. Class not found after a successful dump usually means you guessed the namespace from the README rather than reading src/; the vendor namespace rarely matches the Packagist name (jacklam/php-tools → likely JackLam\PhpTools, but verify).

Migration checklist if you outgrow it: assert wrapper tests pass → copy adopted functions into app/Support with MIT attribution → composer remove jacklam/php-tools → delete the wrapper indirection → done. Keeping the wrapper in place until this point is what makes that a five-minute job instead of a refactor.