From 145d3fc017417829be972f8fd1fe02f05ce0da9d Mon Sep 17 00:00:00 2001 From: dimitri-bouteille Date: Tue, 30 Jan 2024 19:55:43 +0100 Subject: [PATCH] #7 Update documentation --- README.md | 43 ++++++++++----------- doc/documentation.md | 89 -------------------------------------------- doc/filter-data.md | 60 +++++++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 113 deletions(-) delete mode 100644 doc/documentation.md create mode 100644 doc/filter-data.md diff --git a/README.md b/README.md index 8923f2b3..f2c0f4b8 100644 --- a/README.md +++ b/README.md @@ -11,24 +11,33 @@ The ORM also offers a system to simply manage database migrations based on [Phin ### Features -- ✅ Support core WordPress models: `Comment`, `Option`, `Post`, `TermTaxonomy`, `Term`, `User`, `PostMeta` and `UserMeta`. -- ✅ Support core WordPress post type: `Article`, `Attachment` and `Page`. -- ✅ Based on core WordPress database connection (`wpdb` class) -- ✅ Migration with `Phinx` library. -- ❤️ Easy integration of a custom post type. -- ❤️ Easy model creation for projects with custom tables. +- ✅ Support core WordPress models: `Comment`, `Option`, `Post`, `TermTaxonomy`, `Term`, `User`, `PostMeta` and `UserMeta` +- ✅ Support core WordPress post type: `Article`, `Attachment` and `Page` +- ✅ Based on core WordPress database connection (`wpdb` class), no configuration required ! +- ✅ Migration with `Phinx` +- ✅ Custom functions to filter models with meta +- ❤️ Easy integration of a custom post type +- ❤️ Easy model creation for projects with custom tables +- ❤️ All the features available in Eloquent, are usable with this library ! **Not yet developed but planned in a future version:** -- 💡 Create custom comment type -- 💡 Meta casting (e.g. [Attribute Casting](https://laravel.com/docs/10.x/eloquent-mutators#attribute-casting)) +- 🗓️ Create custom comment type +- 🗓️ Meta casting (e.g. [Attribute Casting](https://laravel.com/docs/10.x/eloquent-mutators#attribute-casting)) ### Documentation +This documentation only covers the specific points of this library, if you want to know more about Eloquent, the easiest is to look at [the documentation of Eloquent](https://laravel.com/docs/10.x/eloquent) :) + - [Installation](#installation) - [Use WordPress core models](doc/wordpress-core-models.md) +- [Filter data](/doc/filter-data.md) + - [With findOneBy*](/doc/filter-data.md#with-findoneby) + - [With predefined taps](/doc/filter-data.md#with-taps) + - [With query builder](/doc/filter-data.md#with-query-builder) - [Create custom model](doc/create-model.md) -- [Filter data](/doc/documentation.md#filter-data) + - [Generic Model](doc/create-model.md#generic-model) + - [Custom Post Type Model](doc/create-model.md#custom-post-type-model) - [Migration with Phinx](doc/migration.md) ## Installation @@ -54,21 +63,7 @@ In your PHP script, make sure you include the autoloader: require __DIR__ . '/vendor/autoload.php'; ~~~ -## Introduction - -Simply put, wp-orm is a library that makes it easy to manipulate a WordPress database via the Eloquent ORM. The objective of this library is to **simplify the manipulation of the WordPress database** on large projects - you can also use it for small projects. - -> Eloquent is an object-relational mapper (ORM) that makes it enjoyable to interact with your database. When using Eloquent, each database table has a corresponding "Model" that is used to interact with that table. In addition to retrieving records from the database table, Eloquent models allow you to insert, update, and delete records from the table as well. - -**Here is a list of available features :** - -- The `wpdb` connection is used so **no configuration is needed to use** -- Ability to [create models](doc/documentation.md#model) simply -- WordPress works with custom content types, you can simply [use the default types of WordPress](doc/documentation.md#use-wordpress-models) (page, attachment, ...) and create [custom models for your types](doc/documentation.md#custom-post-type-model) or create [custom model](doc/documentation.md) -- Ability to [filter data](doc/documentation.md#filter-data) easily via taps -- All the features available in Eloquent, are usable with this library - -> 📘 If you want to know more about how Eloquent works, the easiest way is to [read the documentation](https://laravel.com/docs/10.x/eloquent). +🎉 You have nothing more to do, you can use the library now! Not even need to configure database accesses because it's the `wpdb` connection that is used. ## Contributing diff --git a/doc/documentation.md b/doc/documentation.md deleted file mode 100644 index 58f76e18..00000000 --- a/doc/documentation.md +++ /dev/null @@ -1,89 +0,0 @@ -# Documentation - -## Use Wordpress Models - -## Filter data - -You can easily filter data via the `tap` function : - -```php -use Dbout\WpOrm\Taps\Post\IsAuthorTap; -use Dbout\WpOrm\Taps\Post\IsStatusTap; -use Dbout\WpOrm\Enums\PostStatus; -use Dbout\WpOrm\Models\Post; - -$posts = Post::query() - ->tap(new IsAuthorTap(1)) - ->get(); -``` - -This query, returns all user posts with ID 1. - -If you want to apply multiple filters, nothing complicated : - -```php -use Dbout\WpOrm\Taps\Post\IsAuthorTap; -use Dbout\WpOrm\Taps\Post\IsStatusTap; -use Dbout\WpOrm\Enums\PostStatus; -use Dbout\WpOrm\Models\Post; - -$posts = Post::query() - ->tap(new IsAuthorTap(1)) - ->tap(new IsStatusTap(PostStatus::Publish)) - ->get(); -``` - -You can find all the available filters here: [Available filters](available-filters.md). - -## Create Model - -### Model - -Creating a model is very simple, just create a class that extends from `Dbout\WpOrm\Orm\AbstractModel`. - -```php -use Dbout\WpOrm\Orm\AbstractModel; - -class MyModel extends AbstractModel -{ - -} -``` - -Note that we did not tell Eloquent which table to use for our `MyModel` model. The "snake case", plural name of the class will be used as the table name unless another name is explicitly specified. So, in this case, Eloquent will assume the `MyModel` model stores records in the myModels table. You may specify a custom table by defining a table property on your model: - -```php -use Dbout\WpOrm\Orm\AbstractModel; - -class MyModel extends AbstractModel -{ - - protected $table = 'my_table'; -} -``` - -**Note:** Eloquent will also assume that each table has a primary key column named id. You may define a primaryKey property to override this convention. Likewise, you may define a connection property to override the name of the database connection that should be used when utilizing the model. - -Once a model is defined, you are ready to start retrieving and creating records in your table. Note that you will need to place `updated_at` and `created_at` columns on your table by default. If you do not wish to have these columns automatically maintained, set the `$timestamps` property on your model to false. - -> 📘 If you want to know more about creating a model you can look the [Eloquent documentation](https://laravel.com/docs/5.0/eloquent#basic-usage). - -### Custom Post Type Model - -All Custom Post Type (CPT) models extend `Dbout\WpOrm\Models\MyCustomType`. - -```php -use Dbout\WpOrm\Models\CustomPost; - -class MyCustomType extends CustomPost -{ - /** - * @inheritDoc - */ - protected string $_type = 'my_customm_type'; -} -``` - -When retrieving a model `MyCustomType`, the `posts.post_type = my_customm_type` filter will be automatically added to the query. - -**Note:** You cannot use `setPostType` function on CPT models. \ No newline at end of file diff --git a/doc/filter-data.md b/doc/filter-data.md new file mode 100644 index 00000000..584ca4ea --- /dev/null +++ b/doc/filter-data.md @@ -0,0 +1,60 @@ +# Filter data + +You can filter data in several ways: + +- With predefined `findOneBy` functions in place on some models +- With predefined taps +- With Eloquent query builder. If your model has metas, you can use custom filter methods. + +## With findOneBy + +## With taps + +You can easily filter data via the `tap` function : + +```php +use Dbout\WpOrm\Taps\Post\IsAuthorTap; +use Dbout\WpOrm\Taps\Post\IsStatusTap; +use Dbout\WpOrm\Enums\PostStatus; +use Dbout\WpOrm\Models\Post; + +$posts = Post::query() + ->tap(new IsAuthorTap(1)) + ->get(); +``` + +This query, returns all user posts with ID 1. + +If you want to apply multiple filters, nothing complicated : + +```php +use Dbout\WpOrm\Taps\Post\IsAuthorTap; +use Dbout\WpOrm\Taps\Post\IsStatusTap; +use Dbout\WpOrm\Enums\PostStatus; +use Dbout\WpOrm\Models\Post; + +$posts = Post::query() + ->tap(new IsAuthorTap(1)) + ->tap(new IsStatusTap(PostStatus::Publish)) + ->get(); +``` + +You can find all the available filters here: [Available filters](available-filters.md). + +## With query builder + +### Generic + +The Eloquent `all` method will return all of the results in the model's table. However, since each Eloquent model serves as a [query builder](https://laravel.com/docs/10.x/queries), you may add additional constraints to queries and then invoke the `get` method to retrieve the results: + +```php +use Dbout\WpOrm\Models\Post; + +$posts = Post::query() + ->where('ping_status', 'closed') + ->get(); +``` + +> 📘 More information here: [Eloquent query builder](https://laravel.com/docs/10.x/queries). + +### Model with meta relation \ No newline at end of file