[Docs Review] Chapter 11 Database — Technical Accuracy Issues

[lcharette]

Chapter 11: Database — Technical Accuracy Review

Cross-referenced against userfrosting/monorepo. All issues verified against source code.

---

🔴 CRITICAL — Migration dependency namespace uses wrong case (V400 vs v400)

File: app/pages/6.0/11.database/03.migrations/docs.md, lines 183–185

The migration dependency example uses uppercase V400:

use UserFrosting\Sprinkle\Account\Database\Migrations\V400\UsersTable;
use UserFrosting\Sprinkle\Account\Database\Migrations\V400\RolesTable;
use UserFrosting\Sprinkle\Account\Database\Migrations\V400\RoleUsersTable;

Actual monorepo folder: packages/sprinkle-account/app/src/Database/Migrations/v400/ (lowercase v)

PHP namespaces are case-sensitive on Linux/macOS. Using V400 instead of v400 will cause a Class not found error.

Fix: Change all \V400\ to \v400\ in this example.

---

🔴 CRITICAL — users.id column documented as type string

File: app/pages/6.0/11.database/02.default-tables/docs.md, line 65

The table in the docs shows:

Column	Type	Description
id	string	The unique identifier for the user.

Actual migration (UsersTable.php):

$table->increments('id'); // unsigned auto-increment integer, NOT a string

Fix: Change type from string to autoincrement int.

---

🟡 MINOR — System tables path notation wrong for UF6

File: app/pages/6.0/11.database/02.default-tables/docs.md, line 8

"The exceptions are the system tables, which are located in app/system/Database/Migrations."

app/system/Database/Migrations is a UF4/UF5 path. In UF6, Core sprinkle migrations live at vendor/userfrosting/sprinkle-core/app/src/Database/Migrations/ (or in the monorepo at packages/sprinkle-core/app/src/Database/Migrations/).

Fix: Update the path to reflect UF6's package structure, or rephrase to "the Core sprinkle."

---

🟡 MINOR — Sprunje custom filter uses UF-specific ->like() / ->orLike() without explanation

File: app/pages/6.0/11.database/05.data-sprunjing/docs.md, lines 205–211

protected function filterScientificName($query, string $value): static
{
    $query->like('genus', $value)
            ->orLike('species', $value);
    return $this;
}

->like() and ->orLike() are not standard Laravel/Eloquent query builder methods. They are defined in UserFrosting's custom Database\Builder class. While they work in practice for UF models (which use this custom builder), the doc type hint EloquentBuilder|QueryBuilder|Relation implies these are universal methods — they are not.

Fix: Either add a note explaining these are UF-specific builder methods, or replace with standard Eloquent syntax:

$query->where('genus', 'LIKE', "%{$value}%")
      ->orWhere('species', 'LIKE', "%{$value}%");

---

Overall Assessment: Chapter 11

Score: 2 critical, 2 minor. The namespace case issue (#1) is the most dangerous — it will silently break anyone who copies the dependency example verbatim. The id type error (#2) is misleading for developers designing foreign keys against users.id. The other two are lower-risk but affect clarity. Chapter is otherwise well-structured and the API descriptions are accurate.