You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+41-31Lines changed: 41 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,20 +1,21 @@
1
-
# Contributing
1
+
# Contributing to Model ORM
2
2
3
-
Thanks for contributing to `model-orm-php`.
3
+
Thanks for contributing to `model-orm-php`. The project aims to stay small, practical, and dependable across supported databases, so focused changes and clear validation matter.
4
4
5
-
## Ground rules
5
+
## Principles
6
6
7
-
- Be respectful and constructive in issues, pull requests, and review discussion.
8
-
- Keep changes focused. Small, well-scoped pull requests are easier to review and safer to merge.
9
-
- Preserve backward compatibility where practical, or clearly call out breaking changes.
7
+
- Keep changes focused and easy to review.
8
+
- Preserve backward compatibility where practical, or call out breaking behavior clearly.
9
+
- Favor direct, readable PDO-centered code over extra abstraction.
10
+
- Update tests and docs when public behavior changes.
10
11
11
-
## Development setup
12
+
## Local setup
12
13
13
14
Requirements:
14
15
15
16
- PHP `8.3+`
16
17
-`ext-pdo`
17
-
- A PDO driver for the database you want to test against, typically`pdo_mysql` or `pdo_pgsql`
18
+
- A PDO driver for the database you want to test against, usually`pdo_mysql` or `pdo_pgsql`
18
19
- Composer
19
20
20
21
Install dependencies:
@@ -23,12 +24,17 @@ Install dependencies:
23
24
composer install
24
25
```
25
26
26
-
Optional local databases:
27
+
Start optional local databases:
27
28
28
29
```bash
29
30
docker-compose up -d
30
31
```
31
32
33
+
Default local ports:
34
+
35
+
- MySQL/MariaDB on `127.0.0.1:3306`
36
+
- PostgreSQL on `127.0.0.1:5432`
37
+
32
38
## Running checks
33
39
34
40
Run the test suite:
@@ -37,64 +43,68 @@ Run the test suite:
37
43
vendor/bin/phpunit -c phpunit.xml.dist
38
44
```
39
45
40
-
Override the database connection with environment variables when needed:
`Freshsauce\Model\Model`is a lightweight ORM-style base class for PHP applications that want database-backed models without committing to a large framework. Point it at a table, extend the base class, and you get CRUD operations, dynamic finders, counters, and raw query access with very little setup.
7
+
`Freshsauce\Model\Model`gives you the sweet spot between raw PDO and a full framework ORM: fast setup, familiar model-style workflows, and complete freedom to drop to SQL whenever you want.
8
8
9
-
It is designed for projects that value straightforward PHP, direct PDO access, and a small abstraction layer that stays out of the way.
9
+
If you want database-backed PHP models without pulling in a heavyweight stack, this library is built for that job.
10
10
11
-
## Why use it?
11
+
## Why teams pick it
12
12
13
-
-Minimal setup: define a model class and table name, then start reading and writing rows.
14
-
- PDO-first: use the ORM helpers when they help and drop down to raw SQL when they do not.
15
-
-Familiar model flow: create, hydrate, validate, save, update, count, find, and delete.
16
-
-Dynamic finders: call methods such as `findByName()`, `findOneByName()`, `countByName()`, and more.
17
-
-Multi-database support: tested against MySQL/MariaDB, PostgreSQL, and SQLite.
13
+
-Lightweight by design: point a model at a table and start reading and writing records.
14
+
- PDO-first: keep the convenience methods, keep full access to SQL, keep control.
15
+
-Framework-agnostic: use it in custom apps, legacy codebases, small services, or greenfield projects.
16
+
-Productive defaults: CRUD helpers, dynamic finders, counters, hydration, and timestamp handling are ready out of the box.
17
+
-Portable across databases: exercised against MySQL/MariaDB, PostgreSQL, and SQLite.
18
18
19
-
## Installation
20
-
21
-
Install from Composer:
19
+
## Install in minutes
22
20
23
21
```bash
24
22
composer require freshsauce/model
@@ -30,11 +28,9 @@ Requirements:
30
28
-`ext-pdo`
31
29
- A PDO driver such as `pdo_mysql` or `pdo_pgsql`
32
30
33
-
Looking for fuller, example-led usage? See [EXAMPLE.md](EXAMPLE.md).
34
-
35
31
## Quick start
36
32
37
-
Create a table. This quick-start example uses PostgreSQL syntax:
33
+
Create a table. This example uses PostgreSQL syntax:
38
34
39
35
```sql
40
36
CREATETABLEcategories (
@@ -45,7 +41,7 @@ CREATE TABLE categories (
45
41
);
46
42
```
47
43
48
-
If you are using MySQL or MariaDB, use `INT AUTO_INCREMENT PRIMARY KEY` for the `id` column instead.
44
+
If you are using MySQL or MariaDB, use `INT AUTO_INCREMENT PRIMARY KEY` for `id` instead.
49
45
50
46
Connect and define a model:
51
47
@@ -64,7 +60,7 @@ class Category extends Freshsauce\Model\Model
64
60
}
65
61
```
66
62
67
-
Create and save a record:
63
+
Create, read, update, and delete records:
68
64
69
65
```php
70
66
$category = new Category([
@@ -73,35 +69,19 @@ $category = new Category([
73
69
74
70
$category->save();
75
71
76
-
echo $category->id;
77
-
```
78
-
79
-
Read it back:
80
-
81
-
```php
82
72
$loaded = Category::getById($category->id);
83
-
```
84
-
85
-
Update it:
86
-
87
-
```php
88
73
$loaded->name = 'Science Fiction';
89
74
$loaded->save();
90
-
```
91
-
92
-
Delete it:
93
-
94
-
```php
95
75
$loaded->delete();
96
76
```
97
77
98
-
For more end-to-end snippets, see [EXAMPLE.md](EXAMPLE.md).
78
+
That is the core promise of the library: minimal ceremony, direct results.
99
79
100
80
## What you get
101
81
102
-
### CRUD helpers
82
+
### Full record lifecycle helpers
103
83
104
-
The base model gives you the common record lifecycle methods:
84
+
The base model gives you the methods most applications reach for first:
105
85
106
86
-`save()`
107
87
-`insert()`
@@ -114,11 +94,11 @@ The base model gives you the common record lifecycle methods:
114
94
-`last()`
115
95
-`count()`
116
96
117
-
Timestamp columns named `created_at` and `updated_at`are populated automatically on insert and update when present.
97
+
If your table includes `created_at` and `updated_at`, they are populated automatically on insert and update.
118
98
119
99
### Dynamic finders and counters
120
100
121
-
You can query using camelCase dynamic method names:
101
+
Build expressive queries straight from method names:
0 commit comments