Common Laravel Package

Getting Started

• Install with composer require itedev/common, then immediately run composer show itedev/common to confirm the resolved version, PHP constraint, and the actual autoload namespace before writing a single import.
• Open vendor/itedev/common/composer.json and vendor/itedev/common/src/ first. With 2 stars and 0 dependents, the source is the documentation. The autoload block tells you the namespace (likely Ite\Common\ — verify), and the src/ tree is small enough to read in one sitting. Skim every class and note which functions are global vs. namespaced.
• Run a smoke test in php artisan tinker: instantiate the primary helper class(es) and call a few methods with known inputs (null, '', '0', a unicode string, a numeric string). This confirms autoloading works and shows you return types and failure behavior before anything touches app code.
• First real use case: find one controller, job, or console command that already contains ad-hoc utility code — array plucking, string normalization, type coercion — and route a single call site through the package. Do not refactor broadly on day one; prove behavior on one path.

Implementation Patterns

• Treat it as a plain-PHP helper library, not a Laravel package. There is almost certainly no service provider, facade, config, or container binding. You use the classes directly. If you need DI, mockability, or test doubles, wrap the static helpers in a small App\Support\... service class and bind that in a service provider — never resolve the vendor classes from the container.
• Adapter/wrapper pattern is the default. Define a thin internal class (e.g. App\Support\Helpers) that delegates to ite/common. This gives you one swap point if you later vendor, fork, or replace it, and keeps the vendor namespace out of domain logic. It also lets you add Laravel-idiomatic conveniences: accept null, return Collection, accept both arrays and Collection inputs.
• Diff against Illuminate before adopting any method. Laravel already ships Str, Arr, Number, Collection, and a pile of global helpers. For each package method you want, compare behavior on edge cases: null, '', '0', 0, unicode, numeric strings, nested arrays. Adopt the package method only where it clearly does something Illuminate does not do — or does it more cleanly for your specific case.
• Form requests and validation. If the package offers input normalization (trimming, casing, type coercion), call it inside prepareForValidation() on the FormRequest rather than sprinkling it through controllers. It keeps normalization declarative and testable.
• Console and cleanup jobs. This is the sweet spot: data-cleanup commands, import scripts, and internal tooling where convenience helpers genuinely save boilerplate and there is no customer-facing risk. Use it freely there, and keep it out of auth, payments, and anything on the request hot path.
• Keep usage greppable. Always import through the adapter, never reference the vendor namespace directly. A grep for App\Support\Helpers should enumerate every call site, which is what makes an eventual removal cheap.

Gotchas and Tips

• Global function collisions are a real outage risk. If the package defines unguarded global functions, a redeclare against a Laravel helper or a legacy function in your app is a fatal error at boot — total outage, zero warning. Before install, grep the package for function and function_exists, and diff its global function names against Laravel's helper list and your own.
• Pin the version exactly. If it is a 0.x package, semver permits breaking changes on a minor bump. Use an exact constraint ("itedev/common": "0.3.1"), not ^0.3. Add composer.lock to review and check composer audit after every update.
• Silent semantic drift is the sneaky failure. A helper that looks like a Laravel equivalent may behave differently on null or '', producing wrong output rather than an exception. Write contract tests around anything you wrap: assert the adapter's behavior, not the vendor's, so drift is caught.
• Read the license before copy-in. If you decide to vendor a handful of functions into App\Support, confirm the license permits redistribution with attribution and check the exact terms (MIT is fine; anything unusual is not).
• No service provider means no config, no publishing, no migrations. If something is not working, there is no config/common.php to check and no artisan command to debug. Go straight to the source: add dd() inside the vendor method during a spike, and put the call behind the adapter so you can log inputs/outputs from one place.
• Extension points are effectively nil. You cannot override behavior via config or container bindings. The only extension point is the adapter wrapper you write. Do not expect to customize internals; fork or wrap.
• Version and PHP compatibility is your job. Target your app's actual PHP minor version and Laravel major. A PHP upgrade can turn a deprecation inside the package into an error with no upstream fix available — plan to fork under pressure if that happens, which is another argument for keeping all usage behind the adapter.
• Treat it as a source of ideas first. Given 2 stars and 0 dependents, the most maintainable day-to-day use is to read the helpers, copy the two or three that earn their keep into App\Support with attribution and tests, and skip the dependency entirely. The adapter pattern above makes that transition a one-line delete when you're ready.