Skip to content

Commit 2e04bce

Browse files
authored
Add Module and Table Naming Conventions for 3rd parties
1 parent 0875107 commit 2e04bce

File tree

1 file changed

+22
-1
lines changed

1 file changed

+22
-1
lines changed

docs/developers/addons.md

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,14 @@ Which generates the basic structure in the `/modules` folder. After generating t
2323
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).
2424
:::
2525

26+
:::tip
27+
28+
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)
29+
30+
In doing this, you reduce the chance of your module name conflicting directly with another module.
31+
32+
:::
33+
2634
---
2735

2836
## Namespacing
@@ -166,6 +174,8 @@ if(Auth::check())
166174

167175
# Database Access
168176

177+
178+
169179
## Models
170180
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.
171181

@@ -217,6 +227,17 @@ The right relationships make life easier. See the Laravel documentation on relat
217227

218228
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.
219229

230+
:::warning
231+
232+
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.
233+
234+
Not prefixing your tables could lead to unintended consequences, including but not limited to:
235+
236+
* 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.
237+
* Conflicting with other addons by other 3rd party modules that don't head this warning.
238+
239+
:::
240+
220241
! You should *not* be using raw SQL
221242

222243
There is an `artisan` helper to generate migrations:
@@ -366,4 +387,4 @@ $flight->owner_type = Tour::class;
366387
$flight->owner_id = $tour->id;
367388
```
368389

369-
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.
390+
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.

0 commit comments

Comments
 (0)