diff --git a/.php-cs-fixer.php b/.php-cs-fixer.php index 288020c8..bf0dbe5e 100644 --- a/.php-cs-fixer.php +++ b/.php-cs-fixer.php @@ -40,6 +40,7 @@ 'no_unused_imports' => true, 'align_multiline_comment' => true, 'array_indentation' => true, + 'blank_line_after_opening_tag' => false, 'header_comment' => [ 'header' => $header, 'comment_type' => 'PHPDoc', diff --git a/README.md b/README.md index dacfcf83..61d33426 100644 --- a/README.md +++ b/README.md @@ -5,37 +5,29 @@ WordPress ORM with Eloquent is a small library that adds a basic ORM into WordPress, which is easily extendable and includes models for core WordPress models such as posts, post metas, users, comments and more. The ORM is based on [Eloquent ORM](https://laravel.com/docs/eloquent) and uses the WordPress connection (`wpdb` class). -> 💡 To simplify the integration of this library, we recommend using WordPress with one of the following tools: [Bedrock](https://roots.io/bedrock/), [Themosis](https://framework.themosis.com/) or [Wordplate](https://github.com/wordplate/wordplate#readme). +> [!TIP] +> To simplify the integration of this library, we recommend using WordPress with one of the following tools: [Bedrock](https://roots.io/bedrock/), [Themosis](https://framework.themosis.com/) or [Wordplate](https://github.com/wordplate/wordplate#readme). -### Features +## 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), no configuration required ! - ✅ Custom functions to filter models with meta -- ❤️ Easy integration of a custom post type +- ✅ Meta casting (e.g. [Attribute Casting](https://laravel.com/docs/eloquent-mutators#attribute-casting)) +- ❤️ Easy integration of a custom post and comment 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 migration tool with Eloquent](https://github.com/dimitriBouteille/wp-orm/issues/28) -### Documentation +## 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) :) +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/doc/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 taps](/doc/filter-data.md#with-taps) - - [With query builder](/doc/filter-data.md#with-query-builder) -- [Events](/doc/events.md) -- [Create custom model](doc/create-model.md) - - [Generic Model](doc/create-model.md#generic-model) - - [Custom Post Type Model](doc/create-model.md#custom-post-type-model) +You can find all the documentation in [the wiki](https://github.com/dimitriBouteille/wp-orm/wiki). ## Installation diff --git a/doc/available-filters.md b/doc/available-filters.md deleted file mode 100644 index 5a2ceb1c..00000000 --- a/doc/available-filters.md +++ /dev/null @@ -1,25 +0,0 @@ -# Available filters - -## Post - -**Available for all post models** - -- `Dbout\WpOrm\Taps\Post\IsAuthorTap` -- `Dbout\WpOrm\Taps\Post\IsPingStatusTap` -- `Dbout\WpOrm\Taps\Post\IsPostTypeTap` -- `Dbout\WpOrm\Taps\Post\IsStatusTap` - -**Attachment CPT** - -- `Dbout\WpOrm\Taps\Attachment\IsMimeTypeTap` - -## Comment - -- `Dbout\WpOrm\Taps\Comment\IsApprovedTap` -- `Dbout\WpOrm\Taps\Comment\IsCommentTypeTap` -- `Dbout\WpOrm\Taps\Comment\IsUserTap` - -## Option - -- `Dbout\WpOrm\Taps\Option\IsAutoloadTap` - diff --git a/doc/create-model.md b/doc/create-model.md deleted file mode 100644 index c9edb71a..00000000 --- a/doc/create-model.md +++ /dev/null @@ -1,63 +0,0 @@ -# Create Model - -You can create two model types: - -- A model that corresponds to a custom table (e.g. `User`, `Option`, ...) -- A model that corresponds to a Custom Post Type (e.g `Page`, `Attachment`, `Article`, ...) - -## Generic 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/10.x/eloquent#eloquent-model-conventions). - -### Add meta relation - -If your model have metas, you can easily link metas to your model and use custom functions (e.g. `getMeta`, `getMetaValue`, ...). You can look `Dbout\WpOrm\Models\Post` to understand how it works. - -## Custom Post Type Model - -All Custom Post Type (CPT) models extend `Dbout\WpOrm\Models\CustomPost`. - -```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. - -When creating the model, the `post_type` property is automatically filled in with the value `my_customm_type`. - -**Note:** You cannot use `setPostType` function on CPT models. diff --git a/doc/events.md b/doc/events.md deleted file mode 100644 index 854f69c1..00000000 --- a/doc/events.md +++ /dev/null @@ -1,58 +0,0 @@ -# Events - -Eloquent models dispatch several events, allowing you to hook into the following moments in a model's lifecycle: `retrieved`, `creating`, `created`, `updating`, `updated`, `saving`, `saved`, `deleting`, `deleted`, `trashed`, `forceDeleting`, `forceDeleted`, `restoring`, `restored`, and `replicating`. - -> 📘 The following few lines explain how to use events with the library, if you want to know more you can look at the documentation: [Eloquent - Events](https://laravel.com/docs/10.x/eloquent#events). - -## How to use Eloquent events ? - -By default, Eloquent events are not functional in the library since Eloquent is initially used with Laravel which contains all the logic to dispatch the events. However, it is possible to use events via the [illuminate/events](https://packagist.org/packages/illuminate/events) library. - -1. First, install `illuminate/events` : - -```bash -composer require illuminate/events ^10.0 -``` - -2. Setup the dispatcher in your model with `setEventDispatcher` function : - -```php -use Illuminate\Events\Dispatcher; -use Dbout\WpOrm\Orm\AbstractModel; - -class User extends AbstractModel -{ - - protected static function boot() - { - static::setEventDispatcher(new Dispatcher()); - parent::boot(); - } -} -``` - -3. Create your events :) - -```php -use Illuminate\Events\Dispatcher; -use Dbout\WpOrm\Orm\AbstractModel; - -class User extends AbstractModel -{ - - protected static function boot() - { - static::setEventDispatcher(new Dispatcher()); - parent::boot(); - - static::saved(function (User $user) { - // Add your logic here - }); - } -} -``` - -You can now use events, you can use [$dispatchesEvents](https://laravel.com/docs/10.x/eloquent#events) property or [closures](https://laravel.com/docs/10.x/eloquent#events-using-closures). - - -> Warning, if you use abstract class, you must call `setEventDispatcher` in child class. \ No newline at end of file diff --git a/doc/filter-data.md b/doc/filter-data.md deleted file mode 100644 index 4b56a059..00000000 --- a/doc/filter-data.md +++ /dev/null @@ -1,86 +0,0 @@ -# Filter data - -You can filter data in several ways: - -- With `findOneBy` functions in place on some models -- With taps -- With Eloquent query builder. If your model has metas, you can use custom filter methods. - -## With findOneBy - -By default, Eloquent does not offer a magic feature [findOneBy*](https://github.com/laravel/ideas/issues/107), however you can use this feature on some models : - -**User :** - -- `User::findOneByEmail()` -- `User::findOneByLogin()` - -**Option :** - -- `Option::findOneByName()` - -**Post :** - -- `Post::findOneByName()` -- `Post::findOneByGuid()` - -## 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 - -For models that may have metas (e.g. `Post`, `User`, ...), you can filter with `addMetaToFilter`, here is an example that speaks for itself:) - -```php -$products = Post::query() - ->addMetaToFilter('product_type', 'simple') - ->get(); -``` - -> 📘 You can find all functions usable on models with metas here: \ No newline at end of file diff --git a/doc/wordpress-core-models.md b/doc/wordpress-core-models.md deleted file mode 100644 index 587f7947..00000000 --- a/doc/wordpress-core-models.md +++ /dev/null @@ -1,19 +0,0 @@ -# WordPress Core Models - -## Models - -- Comment -- Option -- Post -- PostMeta -- Term -- TermRelationship -- TermTaxonomy -- User -- UserMeta - -## Custom post type - -- Attachment -- Article -- Page \ No newline at end of file diff --git a/src/Orm/Database.php b/src/Orm/Database.php index c14a8e87..bed03f39 100644 --- a/src/Orm/Database.php +++ b/src/Orm/Database.php @@ -255,7 +255,7 @@ public function transaction(\Closure $callback, $attempts = 1) // We'll simply execute the given callback within a try / catch block and if we // catch any exception we can rollback this transaction so that none of this // gets actually persisted to a database or stored in a permanent fashion. - $data = $callback(); + $data = $callback($this); $this->commit(); return $data; } catch (\Exception $e) {