From 2e04bce1af2d716db749aa788aa276b6e9b94842 Mon Sep 17 00:00:00 2001 From: Taylor Broad Date: Tue, 18 Mar 2025 11:40:03 +0900 Subject: [PATCH 1/3] Add Module and Table Naming Conventions for 3rd parties --- docs/developers/addons.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/developers/addons.md b/docs/developers/addons.md index b4dc8de3..db3d2bcd 100644 --- a/docs/developers/addons.md +++ b/docs/developers/addons.md @@ -23,6 +23,14 @@ Which generates the basic structure in the `/modules` folder. After generating t All of the examples below will be based on a module named `Sample`. To see the source for the module, [check it out on GitHub](https://github.com/nabeelio/phpvms-module). ::: +:::tip + +When naming your module, it is recommended that if your module name runs the risk of being generic, to prefix your module name with a unique identifier. For example, instead of naming your module `Tours`, name it `XXTours` (The XX in the example being the identifier or brand name you choose) + +In doing this, you reduce the chance of your module name conflicting directly with another module. + +::: + --- ## Namespacing @@ -166,6 +174,8 @@ if(Auth::check()) # Database Access + + ## Models Models are the more basic way to access your database tables. For example, if you have a table called `sample_table`, a model called `SampleTable` would make most sense. While table names generally refer to objects in the plural, a model is named for an item in it's singular form. @@ -217,6 +227,17 @@ The right relationships make life easier. See the Laravel documentation on relat Laravel includes a way to create and update tables, called [migrations](https://laravel.com/docs/5.5/migrations). Migrations are ways to programmatically define your tables, and let the framework worry about the exact syntax to use. The advantage to this abstraction is being. +:::warning + +When naming your tables, a standard convention that is wise to follow is to prefix your addon's tables with a short indentifier that is unqiue to your addon or group of addons (e.g. `disposable_`, `ch_`, `sp_`, etc.). For example, instead of naming a table `tours`, name it `ch_tours`. This includes pivot tables. See Laravel documentation on how to override the default conventions for table names, foreign relationships, etc. where required. + +Not prefixing your tables could lead to unintended consequences, including but not limited to: + +* Conflicting with future phpVMS core features that would use the same table name, thereby making it more difficult to update phpVMS at a later date. +* Conflicting with other addons by other 3rd party modules that don't head this warning. + +::: + ! You should *not* be using raw SQL There is an `artisan` helper to generate migrations: @@ -366,4 +387,4 @@ $flight->owner_type = Tour::class; $flight->owner_id = $tour->id; ``` -If you have a polymorphic relationship setup on the Tour model, you can use the operators given via Laravel. See the [Polymorphic Relationship docs](https://laravel.com/docs/11.x/eloquent-relationships#polymorphic-relationships) for more info. \ No newline at end of file +If you have a polymorphic relationship setup on the Tour model, you can use the operators given via Laravel. See the [Polymorphic Relationship docs](https://laravel.com/docs/11.x/eloquent-relationships#polymorphic-relationships) for more info. From 6443ac67e8e8e811c3bb0fee90d3cfd11b23dbaa Mon Sep 17 00:00:00 2001 From: Taylor Broad Date: Tue, 18 Mar 2025 11:45:10 +0900 Subject: [PATCH 2/3] fix: move warning block to more logical spot. --- docs/developers/addons.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/developers/addons.md b/docs/developers/addons.md index db3d2bcd..42944b0a 100644 --- a/docs/developers/addons.md +++ b/docs/developers/addons.md @@ -227,17 +227,6 @@ The right relationships make life easier. See the Laravel documentation on relat Laravel includes a way to create and update tables, called [migrations](https://laravel.com/docs/5.5/migrations). Migrations are ways to programmatically define your tables, and let the framework worry about the exact syntax to use. The advantage to this abstraction is being. -:::warning - -When naming your tables, a standard convention that is wise to follow is to prefix your addon's tables with a short indentifier that is unqiue to your addon or group of addons (e.g. `disposable_`, `ch_`, `sp_`, etc.). For example, instead of naming a table `tours`, name it `ch_tours`. This includes pivot tables. See Laravel documentation on how to override the default conventions for table names, foreign relationships, etc. where required. - -Not prefixing your tables could lead to unintended consequences, including but not limited to: - -* Conflicting with future phpVMS core features that would use the same table name, thereby making it more difficult to update phpVMS at a later date. -* Conflicting with other addons by other 3rd party modules that don't head this warning. - -::: - ! You should *not* be using raw SQL There is an `artisan` helper to generate migrations: @@ -254,6 +243,17 @@ The `app/Database/migrations` directory has the core migrations and is a good re !!!! Add new migration files when you have to modify a table, etc, after you've released it into the wild. The migrations that are run are kept track of, so if it's seen that it's already run the file, it won't run it again. +:::warning + +When naming your tables, a standard convention that is wise to follow is to prefix your addon's tables with a short indentifier that is unqiue to your addon or group of addons (e.g. `disposable_`, `ch_`, `sp_`, etc.). For example, instead of naming a table `tours`, name it `ch_tours`. This includes pivot tables. See Laravel documentation on how to override the default conventions for table names, foreign relationships, etc. where required. + +Not prefixing your tables could lead to unintended consequences, including but not limited to: + +* Conflicting with future phpVMS core features that would use the same table name, thereby making it more difficult to update phpVMS at a later date. +* Conflicting with other addons by other 3rd party modules that don't head this warning. + +::: + ### Seeding Data I've added a few extra features, including adding seed data, including adding seeder data. For example, the `Settings` table: From 69d2e39bb4937d5661f9d36a85b31e6ee9261ac9 Mon Sep 17 00:00:00 2001 From: Taylor Broad Date: Tue, 18 Mar 2025 11:50:08 +0900 Subject: [PATCH 3/3] refactor: change a few additional lines. --- docs/developers/addons.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers/addons.md b/docs/developers/addons.md index 42944b0a..dd0edb14 100644 --- a/docs/developers/addons.md +++ b/docs/developers/addons.md @@ -243,9 +243,9 @@ The `app/Database/migrations` directory has the core migrations and is a good re !!!! Add new migration files when you have to modify a table, etc, after you've released it into the wild. The migrations that are run are kept track of, so if it's seen that it's already run the file, it won't run it again. -:::warning +:::warning[Table Name Convention] -When naming your tables, a standard convention that is wise to follow is to prefix your addon's tables with a short indentifier that is unqiue to your addon or group of addons (e.g. `disposable_`, `ch_`, `sp_`, etc.). For example, instead of naming a table `tours`, name it `ch_tours`. This includes pivot tables. See Laravel documentation on how to override the default conventions for table names, foreign relationships, etc. where required. +When naming tables, table names *should* be prefixed with a short indentifier that is unqiue to your addon or group of addons (e.g. `disposable_`, `ch_`, `sp_`, etc.). For example, instead of naming a table `tours`, name it `ch_tours`. This includes pivot tables. See Laravel documentation on how to override the default conventions for table names, foreign relationships, etc. where required. Not prefixing your tables could lead to unintended consequences, including but not limited to: