Weave Code
Common Laravel Package
inisiatif/common
Shared Laravel utilities for Inisiatif Zakat Indonesia: a Branch model, UUID and integer primary key traits, branch relations, Eloquent repository and tagged-cache abstractions, contracts, and common exceptions for consistent apps.
At a glance
Frequently asked questions about Common
- How do I install inisiatif/common in a Laravel application?
- Run composer require inisiatif/common; the CommonServiceProvider is registered automatically through Laravel package discovery. Publishing the configuration with php artisan vendor:publish is optional. If you need a custom table name for the Branch model, set the COMMON_BRANCH_TABLE_NAME environment variable, which defaults to branches.
- Which Laravel and PHP versions does inisiatif/common support?
- The package targets Laravel 10.x, 11.x, and 12.x running on PHP 8.2, 8.3, or 8.4. Because it is proprietary and has sparse release history, confirm vendor support for newer Laravel majors before upgrading. Pin the major version in composer.json so an unexpected namespace or API change cannot break your build.
- Should I use UUID or integer primary keys with inisiatif/common?
- The package ships two traits so the choice is per model: UuidPrimaryKey for UUID keys and IntegerPrimaryKey for auto-incrementing integer keys. A common approach is UUIDs for externally exposed or distributed records such as donors, and integers for internal lookup tables. Decide this per bounded context early, because changing a primary key type after data exists is expensive.
- How do I add a branch relation to an Eloquent model?
- Use the HasBranch trait on any model that belongs to a branch; it also satisfies the HasBranchInterface contract used elsewhere in the package. The related table name is controlled by COMMON_BRANCH_TABLE_NAME and defaults to branches. If your application already has an organization or region table, decide whether the package's Branch model is the system of record or must map to existing master data.
- Can I disable the package migrations if I already have a branches table?
- Yes. Call Common::ignoreMigrations() during application boot to suppress the package's own migrations. This is the recommended path when an existing organization or branch schema already exists, since the default branches migration may conflict with your columns. You still need a decision on who owns that data long term.
- Does the tagged cache feature work with the file or database cache driver?
- No. TaggableCacheAware relies on cache stores that support tagging, which in practice means Redis or Memcached. The file and database drivers will not give you the same invalidation behavior, so production must use a tag-capable store. Plan explicit tests for cache invalidation whenever repository writes occur.
- Is inisiatif/common safe to depend on in production?
- Treat it as an internal or vendor-supported dependency rather than a community package: it is proprietary, has zero stars and zero dependents, and has a sparse release history. Bug fixes, security patches, and support for future Laravel versions may depend entirely on the vendor or an internal fork. A proof of concept plus a documented ownership and exit plan is the responsible way to adopt it.
- How do I upgrade to v3.0.0 of inisiatif/common?
- Version 3 moved contracts from the Inisiatif\Package\Contract namespace to Inisiatif\Package\Common\Contracts. Update all use statements, type hints, and implements clauses that reference the old namespace, then run your test suite. Pin the major version in composer.json before upgrading so mid-project installs stay predictable.
- How do I build a repository with AbstractRepository and an Eloquent model?
- Extend AbstractRepository, set the protected $model property to your Eloquent class, and make that model implement ResourceInterface. The base class handles the standard model operations defined by ModelRepositoryInterface. Keep custom, performance-sensitive queries in the concrete repository so the abstraction does not hide Eloquent behavior you need to tune.
- What are the alternatives to inisiatif/common for branch-aware Laravel apps?
- Teams that want direct Eloquent usage can rely on global scopes, and teams with broader tenancy requirements often use Spatie multitenancy or admin stacks such as Filament or Nova. This package is a better fit as an internal platform layer for branch-heavy services like donor management, fund distribution, or regional reporting. Small applications or teams already committed to another tenancy solution rarely need it.
Weaver
How can I help you explore Laravel packages today?