Skip to content

Commit

Permalink
.MD
Browse files Browse the repository at this point in the history
  • Loading branch information
@anthonybudd
anthonybudd committed Feb 28, 2017
1 parent 4894b6b commit 2456a81
Showing 1 changed file with 142 additions and 163 deletions.
305 changes: 142 additions & 163 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@

### A simple class for creating active record, eloquent-esque models of WordPress Posts.

####Introduction: [Medium Post](https://medium.com/@AnthonyBudd/wp-model-6887e1a24d3c)

####Advanced Functionality: [Medium Post](https://medium.com/@AnthonyBudd/wp-model-advanced-b44f117617a7)


```php

Class Product extends WP_Model
Expand All @@ -25,10 +30,6 @@ $book->save();

```

Introduction: [Medium Post](https://medium.com/@AnthonyBudd/wp-model-6887e1a24d3c)

Advanced Functionality: [Medium Post](https://medium.com/@AnthonyBudd/wp-model-advanced-b44f117617a7)

***

### Features
Expand Down Expand Up @@ -154,7 +155,7 @@ $firstProducts = Product::in([1, 2, 3, 4]);

### Chainable Finders

If you prefur to find your models using a chainable OOP style syntax the query() method is a chainable wrpper for the where() method. Each of the finder chainable finder methods meta() and tax can accept a variging amout of argumnts
If you prefer to find your models using a chainable OOP style syntax the query() method is a wrapper for the where() method. Each of the finder chainable finder methods meta() and tax can accept a varying amount of arguments. You must call the execute() method to run the query.

#### meta()
```php
Expand All @@ -164,15 +165,15 @@ Product::query()
->meta('meta_key', 'compare', meta_value', 'type')
```

#### meta()
#### tax()
```php
Product::query()
->meta('meta_key', 'meta_value')
->meta('meta_key', 'compare', meta_value')
->meta('meta_key', 'compare', meta_value', 'type')
->tax('taxonomy', 'terms')
->tax('taxonomy', 'field', 'terms')
->tax('taxonomy', 'field', 'operator', 'terms')
```

#### example()
#### Example
```php
$products = Product::query()
->meta('color', 'red')
Expand All @@ -184,135 +185,6 @@ $products = Product::query()
->execute();
```


### Where()

where() is a simple interface into WP_Query, the method can accept two string arguments (meta_value and meta_key). For complex queries supply the method with a single array as the argument. The array will be automatically broken down into tax queries and meta queries, WP_Query will then be executed and will return an array of models.

```php
$greenProducts = Product::where('color', 'green');

$otherProducts = Product::where([
[
'key' => 'color',
'value' => 'green',
'compare' => '!='
],[
'taxonomy' => 'category',
'terms' => ['home', 'garden']
]
]);
```

### Custom Finders

The finder() method allows you to create a custom finder method.
To create a custom finder first make a method in your model named your finders name and prefixed with '_finder' this method must return an array. The array will be given directly to the constructer of a WP_Query. The results of the WP_Query will be returned by the finder() method.

If you would like to post-process the results of your custom finder you can add a '_postFinder' method. This method must accept one argument which will be the array of found posts.

```php

Class Product extends WP_Model
{
...

public function _finderHeavy()
{
return [
'meta_query' => [
[
'key' => 'weight',
'compare' => '>',
'type' => 'NUMERIC',
'value' => '1000'
]
]
];
}

// Optional
public function _postFinderHeavy($results)
{
return array_map(function($model){
if($model->color == 'green'){
return $model->color;
}
}, $results);
}
}

$heavyProducts = Product::finder('heavy');
```


***

## Taxonomies

If you would like to have any taxonomies loaded into the model, add the optional public property $taxonomies (array of taxonomy slugs) to the class.
```php
Class Product extends WP_Model
{
...
public $taxonomies = [
'category',
];
}
```

You can set a models taxonomies by providing it in the array when instantiating the model, this array can be a combination of term slugs or term _ids.
The model's terms can be accesed by getting the property named the taxonimy name.
```php
$product = Product::insert([
'title' => 'product',
'color' => 'blue',
'weight' => '250',
'category' => ['home', 3]
]);

$product->category; // ['Home', 'Office'];
```

If you want direct access to the taxonomy objects you can do this by using the getTaxonomy() method. The first argument is the taxonomy name, the second argument is optional and it is the property to be extracted from the term object. Not providing the second argument will return WP_Term objects.

```php
$product->getTaxonomy('category'); // [WP_Term, WP_Term];
$product->getTaxonomy('category', 'term_id'); // [2, 3];
$product->getTaxonomy('category', 'name'); // ['Home', 'Office'];
```

You can add a taxonomy by using the addTaxonomy() method. The first argument is the taxonomy name, the second argument can either be the term_id (must be an integer) or the term slug (must be provided as a string). If the term could not be found the method will return FALSE.

If you want to add multiple terms to a model you can use the addTaxonomies() method. The second argument must be an array of term slugs and/or term_ids.

```php
$product->addTaxonomy('category', 'home');
$product->addTaxonomy('category', 3);

$product->addTaxonomies('category', ['home', 'office']);
$product->addTaxonomies('category', ['home', 3]);
$product->addTaxonomies('category', [2, 3]);
```

To remove terms from the model you can use the removeTaxonomy() and removeTaxonomies() methods. These work in the same fashion as the addTaxonomy() and addTaxonomies() method as shown above.
```php
$product->removeTaxonomy('category', 'home');
$product->removeTaxonomy('category', 3);

$product->removeTaxonomies('category', ['home', 'office']);
$product->removeTaxonomies('category', [2, 3]);
```

To remove all terms associated to the model of the specified taxonomy use clearTaxonomy().
```php
$product->clearTaxonomy('category');
$product->getTaxonomy('category'); // [];
```

No change to the models taxonomies will be committed to the database untill you call the save() method.


***

### Delete()
Expand Down Expand Up @@ -447,6 +319,69 @@ Result:
}
```

***
### Advanced Finding

#### Where()

where() is a simple interface into WP_Query, the method can accept two string arguments (meta_value and meta_key). For complex queries supply the method with a single array as the argument. The array will be automatically broken down into tax queries and meta queries, WP_Query will then be executed and will return an array of models.

```php
$greenProducts = Product::where('color', 'green');

$otherProducts = Product::where([
[
'key' => 'color',
'value' => 'green',
'compare' => '!='
],[
'taxonomy' => 'category',
'terms' => ['home', 'garden']
]
]);
```

#### Custom Finders

The finder() method allows you to create a custom finder method.
To create a custom finder first make a method in your model named your finders name and prefixed with '_finder' this method must return an array. The array will be given directly to the constructer of a WP_Query. The results of the WP_Query will be returned by the finder() method.

If you would like to post-process the results of your custom finder you can add a '_postFinder' method. This method must accept one argument which will be the array of found posts.

```php

Class Product extends WP_Model
{
...

public function _finderHeavy()
{
return [
'meta_query' => [
[
'key' => 'weight',
'compare' => '>',
'type' => 'NUMERIC',
'value' => '1000'
]
]
];
}

// Optional
public function _postFinderHeavy($results)
{
return array_map(function($model){
if($model->color == 'green'){
return $model->color;
}
}, $results);
}
}

$heavyProducts = Product::finder('heavy');
```

***


Expand Down Expand Up @@ -486,29 +421,6 @@ Class Product extends WP_Model
}
```

***

### Patching
By calling the static methods patchable whenever a form is submitted with the field _model. It will automatically create a new model or update an existing model if the field _id is also present.

```php
Product::patchable();
```

```html
<form action="" method="post" enctype="multipart/form-data">
<input type="hidden" name="_model" value="product">

<!-- Omitting this will create a new model -->
<input type="hidden" name="_id" value="15">

<input type="text" name="color" value="red">
<input type="submit" value="Submit" name="submit">
</form>
```

***

### Helper Properties

The $new property will return true if the model has not been saved in the Database yet.
Expand Down Expand Up @@ -570,4 +482,71 @@ Product::asList('post_title')
16 => "Product 2",
17 => "Product 3"
]
```
```

## Taxonomies

If you would like to have any taxonomies loaded into the model, add the optional public property $taxonomies (array of taxonomy slugs) to the class.
```php
Class Product extends WP_Model
{
...
public $taxonomies = [
'category',
];
}
```

You can set a models taxonomies by providing it in the array when instantiating the model, this array can be a combination of term slugs or term _ids.
The model's terms can be accessed by getting the property named the taxonomy name.
```php
$product = Product::insert([
'title' => 'product',
'color' => 'blue',
'weight' => '250',
'category' => ['home', 3]
]);

$product->category; // ['Home', 'Office'];
```

If you want direct access to the taxonomy objects you can do this by using the getTaxonomy() method. The first argument is the taxonomy name, the second argument is optional and it is the property to be extracted from the term object. Not providing the second argument will return WP_Term objects.

```php
$product->getTaxonomy('category'); // [WP_Term, WP_Term];
$product->getTaxonomy('category', 'term_id'); // [2, 3];
$product->getTaxonomy('category', 'name'); // ['Home', 'Office'];
```

You can add a taxonomy by using the addTaxonomy() method. The first argument is the taxonomy name, the second argument can either be the term_id (must be an integer) or the term slug (must be provided as a string). If the term could not be found the method will return FALSE.

If you want to add multiple terms to a model you can use the addTaxonomies() method. The second argument must be an array of term slugs and/or term_ids.

```php
$product->addTaxonomy('category', 'home');
$product->addTaxonomy('category', 3);

$product->addTaxonomies('category', ['home', 'office']);
$product->addTaxonomies('category', ['home', 3]);
$product->addTaxonomies('category', [2, 3]);
```

To remove terms from the model you can use the removeTaxonomy() and removeTaxonomies() methods. These work in the same fashion as the addTaxonomy() and addTaxonomies() method as shown above.
```php
$product->removeTaxonomy('category', 'home');
$product->removeTaxonomy('category', 3);

$product->removeTaxonomies('category', ['home', 'office']);
$product->removeTaxonomies('category', [2, 3]);
```

To remove all terms associated to the model of the specified taxonomy use clearTaxonomy().
```php
$product->clearTaxonomy('category');
$product->getTaxonomy('category'); // [];
```

No change to the models taxonomies will be committed to the database until you call the save() method.


***

0 comments on commit 2456a81

Please sign in to comment.