Custom Post type utility functions.
A PHP Class for creating WordPress Custom Post Types easily, (*1)
Installation
Install with composer
Run the following in your terminal to install PostTypes with Composer., (*2)
$ composer require "93digital/custom-post-type @dev"
Below is a basic example of getting started with the class, though your setup maybe different depending on how you are using composer., (*3)
false,
)
);
```
All available options are on the [WordPress Codex](https://codex.wordpress.org/Function_Reference/register_post_type)
## Add Taxonomies
Adding taxonomies to a post type is easily achieved by using the taxonomy() method.
### Create new taxonomy
To create a new taxonomy simply pass the taxonomy name to the taxonomy() method. Labels and the taxonomy slug are generated from the taxonomy name.
```
function $books->taxonomy( string $singular_name, string $plural, array args );
```
#### Parameters:
- *$singular* (string|required) singular name.
- *$plural* (string) plural name, by default will append 's' at the singular one.
- *args* (array) array of [Arguments](https://codex.wordpress.org/Function_Reference/register_taxonomy#Arguments).
#### Example
```
$books->taxonomy( 'Genre' );
```
### Defining names
You can define the plural name by passing it as secondary parameter.
- singular is the singular label for the post type
- plural is the plural label for the post type
- slug is the post type slug used in the permalinks
```
$books->taxonomy( 'Genre', 'Genres' );
```
### Adding options
You can further customise taxonomies by passing an array of options as the 3rd argument to the method.
```
$options = array(
'heirarchical' => false
);
$books->taxonomy( 'Genre', 'Genres', $options );
```
All available options are on the [WordPress Codex](https://codex.wordpress.org/Function_Reference/register_taxonomy)
## The settings page
When setting the 'has_archive' parameter to true, the class will add a sub page for the new CPT, called:
_[CPT Plura] Settings_
The page can be used to add fields using ACF, and will be visible inside the *Option page* option.
To retrieve the information stored inside the custom page, use:
```
get_field( '[THE OPTION SLUG]', 'cpt-[SINGULAR NAME]' );
the_field( '[THE OPTION SLUG]', 'cpt-[SINGULAR NAME]' );
```
_the 2nd attribute is the same of the "page" one of the setting page url_
### Example
```
get_field( 'year', 'cpt-book' );
the_field( 'year', 'cpt-book' );
```
*By default the 'has_archive' parameter is set to true.*
## Loop the items
The class has builtin methods to easily loop the custom posts, without manually calling the WP_Query class.
> **Note:** For performance purpose "no_found_rows" is set to true.
> If pagination is required, you need to set it to true.
### Simple loop
To simple loop through the items using the default WP_Query parameters just use the variable registered before as:
```
This is a simple loop
have_posts() ) : $books->the_post(); ?>
, (*4)
In this example $books is the name of the variable used to register the custom post type in WP., (*5)
Get posts
The following functions allows to customise the WP_Query arguments used for the Simple loop., (*6)
Get the CPT posts using custom parameters.
function get_posts( $posts_per_page = 0, $args );
-
$posts_per_page (int) number of post to show per page. Default = 0 (does not set the parameter for WP_Query)
-
$args (array) array of arguments to pass to WP_Query
Example
// Get the first 10 books.
$books->get_posts( 10 );
// Passing offset attribute.
$books->get_posts( 10, array( 'offset' => 11 ) );
// If don't want to specify the post limit, just pass 0 as first parameter.
$books->get_posts( 0, array( 'offset' => 11 ) );
Using with simple loop:, (*7)
$books->get_posts( 0, array( 'offset' => 11 ) );
while ( $books->have_posts() ) : $books->the_post();
...
endwhile;
If pagination is required, (*8)
$books->get_posts( 0, array( 'offset' => 11, 'no_found_rows' => true ) );
while ( $books->have_posts() ) : $books->the_post();
...
endwhile;
Get posts by meta values
$books->get_posts_by_meta( string $meta_key, mixed $meta_value, string $meta_compare, int $post_limit = 0 );
Get posts by taxonomy
For all the taxonomies registered using the built in Create new taxonomy method, is available the following virutal method:, (*9)
$books->get_posts_by_[taxonomy-slug]( string|array values );
where:, (*10)
-
$books is the variable name previously used to register the custom post type.
-
taxonomy_slug is the slug of the taxonomy we want to filter.
- $values list of slugs to filter.
Example
Suppose we register the taxonomy genre for our cpt:, (*11)
$books = new PostType( 'Book' );
$books->taxonomy( 'Genre' );
now we can easily filter our posts:, (*12)
$book_cpt->get_posts_by_genre( 'horror' );
we can also pass an array of slugs if needed to filter by multiple values, (*13)
Single taxonomy
An alternative method to filter by single taxonomy is:, (*14)
$books->get_posts_by_term( string $taxonomy, string|int|array $slugs, string $field = 'slug', array $args = array() );
Parameters:
-
$taxonomy the taxonomy name
-
$slugs the slugs/ids to filter
-
$field Select taxonomy term by. Possible values are 'term_id', 'name', 'slug' or 'term_taxonomy_id'. Default value is 'slug'.
-
$args additional arguments to pass to the WP_Query class.
Multiple taxonomies
$books->get_posts_by_terms( array $terms, $string relation = 'AND', array $args = array() );
Parameters:
-
$terms associative array with the taxonomies to filter.
-
$relation The logical relationship between each inner taxonomy.
-
$args additional arguments to pass to the WP_Query class.
Example:
$books = new PostType( 'Book' );
$books->taxonomy( 'Genre' );
$books->taxonomy( 'Language' );
/**
* Retrieves all the "Horror" books written in "Italian" and "German"
*/
$terms = array(
'genre' => 'horror',
'language' => array( 'italian', 'german' ),
);
$books = $books->get_posts_by_terms( $terms );
Set the order
By default posts are ordered by Title: ASC, (*15)
$books->set_order( ORDER_BY, ORDER );
The WP_Query object
Is possible to access to the last executed WP_Query object with:, (*16)
$query = $books->wp_query();
Admin Edit Screen
Filters
When you register a taxonomy it is automagically added to the admin edit screen as a filter and a column., (*17)
You can define what filters you want to appear by using the filters() method:, (*18)
$books->filters( array( 'genre' ) );
The class has 2 utility functions to easily add meta box for the CPT registered., (*19)
function add_meta_box( $title, $callback, $context = 'normal', $priority = 'low' );
Example
$books->add_meta_box( 'My meta box', 'my_callback_function' );
function my_callback_function( $post ) {
}
An alternative method, instead of setting $contex = 'side', to register a meta box into the sidebar is:, (*20)
function add_sidebar_meta_box( $title, $callback, $priority = 'low' );
Example
$books->add_sidebar_meta_box( 'My meta box', 'my_callback_function' );
function my_callback_function( $post ) {
}
Columns
Add a custom column to the CPT list:
function add( $column, $label = null, $callback = null, $position = null );
Example
$books->columns()->add( 'genre', 'Genre', 'genre_callback', 2 );
function genre_callback( $key, $post_id ) {
echo $post_id;
}
Hide a column from the CPT list
/**
* Add a column to hide
*
* @param string $column the slug of the column to hdie
*/
function hide( $columns )