Sushi Laravel Package

Getting Started

Start by installing the package and ensuring the pdo-sqlite extension is enabled in your PHP environment:

composer require calebporzio/sushi

Then, create a model and use the Sushi trait along with a $rows array:

use Illuminate\Database\Eloquent\Model;
use Sushi\Sushi;

class Country extends Model
{
    use Sushi;

    protected $rows = [
        ['id' => 1, 'name' => 'United States', 'code' => 'US'],
        ['id' => 2, 'name' => 'Canada', 'code' => 'CA'],
    ];
}

Now you can query it like any Eloquent model:

$country = Country::where('code', 'US')->first();

Ideal for static reference data (e.g., countries, states, roles, settings) where database persistence isn’t needed.

Implementation Patterns

• Static reference data: Use $rows for immutable, small-to-medium datasets (e.g., tax rates, timezones, product categories).
• Dynamic data via getRows(): Implement getRows() to source data at runtime (e.g., from a config file, API, or CSV). Combine with sushiShouldCache() and sushiCacheReferencePath() to cache results and watch external files for cache invalidation.
• Model relationships: Reference Sushi models in relationships (belongsTo, hasMany) with regular Eloquent models—just avoid whereHas()/whereDoesntHave() due to cross-database limitations.
• Validation rules: Use exists:App\Models\YourModel,column in validation rules, as the sushi. connection prefix is no longer needed (v2.3.1+).
• Schema customization: Define $schema = ['column' => 'type'] to override auto-detected column types (e.g., force integer for '001' → 1).
• Post-migration hooks: Use afterMigrate(Blueprint $table) to add indexes or constraints (e.g., $table->index('name')).

Gotchas and Tips

• whereHas doesn’t work across Sushi and database-backed models due to separate SQLite connections—prefetch related data or use raw queries if needed.
• String primary keys require:

  public $incrementing = false;
  protected $keyType = 'string';
  

• Empty datasets will fail unless you define $schema—essential for models that may return no rows from getRows().
• Caching behavior:
  • $rows is cached automatically and busts when the model file changes.
  • getRows() datasets are not cached unless sushiShouldCache() returns true.
  • Use sushiCacheReferencePath() to tie cache invalidation to an external file (e.g., CSV).
• Chunk inserts: If inserting large datasets, set public $sushiInsertChunkSize = 50; to avoid SQLite’s too many SQL variables error.
• Column type inference: Auto-detects from values (123 → integer, '123' → string), but explicit $schema ensures correctness.
• Timestamps: If $timestamps = true, created_at/updated_at columns are auto-added—even when using $rows.
• Debugging: Check cache files at storage/sushi/ (customize via config('sushi.cache-prefix')) or enable sushi.log debugging (if added by config).