Weave Code
Common Laravel Package
inisiatif/common
Paket common untuk Inisiatif Zakat Indonesia (Laravel 10–12, PHP 8.2+): menyediakan model Branch, traits (UUID/int primary key, HasBranch), kontrak & abstract repository pattern, serta dukungan cache tagging untuk kebutuhan lintas aplikasi.
At a glance
Frequently asked questions about Common
- How do I integrate this package into an existing Laravel 11 project with integer primary keys?
- Use the `IntegerPrimaryKey` trait in your models instead of `UuidPrimaryKey`. The package auto-discovers the service provider, so no manual registration is needed. Publish configs if you want to customize the `branches` table name via `COMMON_BRANCH_TABLE_NAME`.
- Can I skip the Branch model if my app doesn’t need multi-branch support?
- Yes, you can skip the `branches` table migration by not publishing the config or overriding the default table name. The package remains functional without it, but traits like `HasBranch` won’t work. Use Laravel’s built-in features (e.g., scopes) for alternative multi-tenancy.
- What’s the performance impact of using AbstractRepository vs. direct Eloquent queries?
- The repository layer adds minimal overhead for CRUD operations but introduces abstraction for complex queries. Benchmark your use case—direct Eloquent is faster for simple queries, while repositories shine in large-scale apps with shared business logic. Cache tagging (`TaggableCacheAware`) further optimizes read-heavy workloads.
- Does this package support Laravel 12’s new features like Livewire integration or API resources?
- The package is compatible with Laravel 12 but doesn’t explicitly extend Livewire or API resources. Use it alongside Laravel’s native features—e.g., pair `ResourceInterface` with Laravel’s API resources for consistent domain modeling. No conflicts or breaking changes are expected.
- How do I migrate from integer to UUID primary keys in an existing database?
- Backup your database first. Use Laravel migrations to add a `uuid` column, copy data, then drop the old primary key. The `UuidPrimaryKey` trait handles UUID generation automatically. Test thoroughly—UUIDs require adjustments to foreign keys and indexes.
- Are there alternatives to this package for repository patterns in Laravel?
- Yes. For repositories, consider `spatie/laravel-repository` (more community-backed) or `laravel-eloquent-repository`. For multi-tenancy, `spatie/laravel-multitenancy` or `filament/spatie-laravel-tenancy` are popular. This package’s unique value lies in its branch-specific traits and Inisiatif Zakat’s domain contracts.
- How do I customize the cache tagging behavior in TaggableCacheAware?
- Extend the `TaggableCacheAwareInterface` and override methods like `getCacheTags()`. Use Laravel’s `cache()->tags()` under the hood. Example: `public function getCacheTags(): array { return ['model_'.$this->modelName]; }`. Publish the config to adjust default tag prefixes.
- Will this package work with Laravel’s first-party testing tools like Pest or PHPUnit?
- Yes, the package is framework-agnostic. Use Laravel’s testing helpers (e.g., `actingAs()`, `refreshDatabase()`) as usual. Mock repositories by implementing `ModelRepositoryInterface` in tests. Cache tagging works with Laravel’s `Cache` facade in test environments.
- What happens if I upgrade to Laravel 13—will this package break?
- No guarantees, as the package isn’t actively maintained by the Laravel core team. Monitor the repo for updates or fork it. The proprietary license may restrict modifications. Test thoroughly in a staging environment before upgrading.
- How do I handle exceptions thrown by this package in production?
- Use Laravel’s exception handling (`app/Exceptions/Handler.php`) to log custom exceptions like `DomainException`. Convert them to HTTP responses or notify admins. Example: `throw new DomainException('Invalid branch ID');` in your repository logic.
Weaver
How can I help you explore Laravel packages today?