Core Bundle Laravel Package

Getting Started

This package is still pre-1.0 (0.1.26), so treat the CHANGELOG as the primary source of truth before reading the README — patch-level releases here have shipped behaviour changes (see 0.1.26 below) that would be minor/major bumps elsewhere.

1. composer require <vendor>/<package> and, if the package ships one, php artisan vendor:publish --tag=<package>-config.
2. Read, in this order: CHANGELOG.md → config/<package>.php → the service provider's register()/boot() → the class that builds SQL identifiers. The identifier-wrapping code is the part that changed in 0.1.26 and is where most integration bugs will surface.
3. Pin the version explicitly ("<vendor>/<package>": "0.1.26") rather than relying on ^0.1. A quoting change in a patch release can alter generated SQL across your whole app.
4. First use case: point the package at a table whose name collides with a MySQL 8.0 reserved word — groups, rank, system, window, lead, rows, cume_dist — and inspect the emitted SQL. Before 0.1.26 these names produced syntax errors against MySQL 8; as of 0.1.26 the package emits `table_name` and the queries should run.

// Smoke test: confirm the identifier is quoted, not interpolated raw
$sql = <Package>::for('groups')->toSql();
$this->assertStringContainsString('`groups`', $sql);

If you are not on MySQL (or are on MySQL with ANSI_QUOTES enabled), run this smoke test on your actual driver before adopting — the backtick fix is MySQL-shaped, and 0.1.26's changelog says nothing about other platforms.

Implementation Patterns

Let the package quote; stop quoting yourself. The single most important pattern after 0.1.26 is to pass bare table names everywhere. Any backticks you added manually to work around the old behaviour will now be double-wrapped ( groups ) and break. Audit for '' . $table . ''-style interpolation in your own query-building code and remove it.

// Before 0.1.26 (workaround) — now produces broken SQL
$builder->table('`groups`');

// After 0.1.26
$builder->table('groups');

Derive the name from the model, not a literal. Feed $model->getTable() so that protected $table overrides, tenant-prefixed tables, and dynamic table swaps all flow through the package's quoting path:

$report = <Package>::for((new Group)->getTable())->...;

Prefer the package over DB::raw() for anything touching identifiers. If the package owns identifier quoting, keeping raw SQL out of your call sites means the next quoting fix reaches you for free. Where you must drop to raw SQL, use Laravel's grammar helpers so you inherit the connection's real quoting rules:

$grammar = DB::connection()->getQueryGrammar();
DB::table($grammar->wrapTable('groups'))->where(...);

Configuration-driven table lists. If the package reads table names from config (common for audit/report/export tooling), keep them unquoted and let the package wrap them; then assert on generated SQL in a test so a future quoting change is a red test rather than a production 500.

Multi-connection awareness. In apps with MySQL plus Postgres/SQLite (tenants, read replicas, analytics), each connection needs its own verification. Wrap your smoke test in a dataset over config('database.connections') and skip drivers you do not actually support.

Regression guard for keyword conflicts. Add a test that iterates a short list of MySQL 8.0 reserved words and asserts successful compilation against MySQL:

#[DataProvider('reservedWords')]
public function test_reserved_word_tables_are_quoted(string $table): void
{
    $this->assertStringContainsString("`{$table}`", <Package>::for($table)->toSql());
}

Gotchas and Tips

• Backticks are MySQL-specific. PostgreSQL and SQL Server need "identifier" / [identifier]; SQLite tolerates backticks but it is non-standard and not guaranteed. If you run anything other than MySQL, test 0.1.26 explicitly — the changelog scopes the fix to MySQL 8.0 keyword conflicts only.
• ANSI_QUOTES mode. On MySQL with sql_mode including ANSI_QUOTES, backticks are no longer valid identifier quotes. Check SELECT @@sql_mode in each environment before upgrading.
• Aliases and schema-qualified names are the classic failure point. `db`.`table`, `table` AS `t`, `table` `t` — naive wrapping tends to produce `db.table` or `table as t`. Test these forms directly; they are rarely covered by the release that introduced quoting.
• Double-wrapping from your own code is the most likely upgrade breakage. Grep for backticks in config files, migration-adjacent helpers, and Blade/report templates that build SQL strings.
• Raw whereRaw/orderByRaw fragments are still yours to quote. The 0.1.26 change covers table identifiers the package emits, not identifiers you hand into raw clauses — a keyword-named column will still blow up.
• Cached/compiled SQL. If you cache generated SQL, query-plan snapshots, or serialized builders, flush them after upgrading; stored strings carry the old unquoted form.
• Semver signal. Identifier quoting shipped in a patch bump on a 0.x package — assume other behaviour can shift in patches. Pin the exact version and read every changelog entry, not just the one that broke something.
• Extension points to check if you need non-MySQL quoting: look for a grammar/identifier-wrapper class or a quote/wrap/escapeIdentifier method you can bind or override in a service provider. If no such seam exists, that is worth filing upstream — it is the natural place for a Connection-aware quoting strategy.
• Debugging: dump toSql() and getBindings() together before executing, and reproduce against a real MySQL 8 instance rather than SQLite, which will happily accept backticks and hide keyword-collision bugs.