Clarkson Core provides a way for theme developers to work with objects.
These objects represent different entities in your WordPress site, such as posts, users and terms.
With these objects, you can create custom features, reuse logic and extend the way WordPress works.
Objects are created mainly through the \Clarkson_Core\Objects class.
This class takes a resource and automatically tries to determine the best fitting object for it.
When you do not extend any objects in your theme, Clarkson Core will fall back to default objects, such as \Clarkson_Core\WordPress_Object\Clarkson_Object.
If you do require custom features on your objects, you can extend the default object with your own.
Much like the way the WordPress template hierarchy tries to determine the most applicable template for a page, Clarkson Core tries to load the most applicable PHP object.
It is possible to register post types and taxonomies with names that can not lead to valid PHP class names.
Clarkson Core always normalizes an object name by making it lowercase, and replacing all non-alphanumeric characters with an _.
Eg: Example-PostType becomes example_posttype.
You can use Composer PSR-4 autoloading to define where Clarkson Core should look for these objects. You can define the \Clarkson_Core\WordPress_Object namespace.
"autoload": {
"psr-4": {
"Clarkson_Core\\WordPress_Object\\": "themes/child-theme/app/WordPress_Objects/"
}
}
\Clarkson_Core\WordPress_Object\$post_type
\Clarkson_Core\WordPress_Object\base_object
\Clarkson_Core\WordPress_Object\Clarkson_Object (default)
\Clarkson_Core\WordPress_Object\$taxonomy
\Clarkson_Core\WordPress_Object\base_term
\Clarkson_Core\WordPress_Object\Clarkson_Term (default)
\Clarkson_Core\WordPress_Object\user
\Clarkson_Core\WordPress_Object\Clarkson_User (default)
\Clarkson_Core\WordPress_Object\$template
\Clarkson_Core\WordPress_Object\base_template
\Clarkson_Core\WordPress_Object\Clarkson_Template (default)
\Clarkson_Core\WordPress_Object\post_type_$post_type
\Clarkson_Core\WordPress_Object\base_post_type
\Clarkson_Core\WordPress_Object\Clarkson_Post_Type (default)
\Clarkson_Core\WordPress_Object\taxonomy_$taxonomy
\Clarkson_Core\WordPress_Object\base_taxonomy
\Clarkson_Core\WordPress_Object\Clarkson_Taxonomy (default)
\Gutenberg\Blocks\$block_name
\Gutenberg\Blocks\base_block
\Clarkson_Core\Gutenberg\Block_Type (default)
You can use the hierarchy in WordPress objects to define custom behaviour.
As an example:
<?php
// wp-content/themes/child-theme/app/WordPress_Objects/event.php
namespace Clarkson_Core\WordPress_Object;
class event extends base_object{
public static $type = 'event';
public function get_event_date(): \DateTime{
// This method is only available on the `event` object.
}
}
As you can see in the example above, you can create an object that specifically handles event functions, for the event posttype.
In the example, this event objects extends from base_object. You can use base_object as a way to create methods that are available on all objects within your theme.
<?php
// wp-content/themes/child-theme/app/WordPress_Objects/base_object.php
namespace Clarkson_Core\WordPress_Object;
class base_object extends Clarkson_Object{
public function has_teaser_video(): string{
// This method is available on all objects Clarkson Core loads.
}
}
The created base_object extends from the default Clarkson_Object, that comes with Clarson Core.
The original Clarkson_Object provides a lot of utility functions, which you can find in the API reference.
When retrieving data from the database, you directly want to have the correct object to work with. Here we list some methods of getting objects and converting standard WordPress objects.
Every type of object has a get_many function. This allows you to perform a database query for the resource type and the result will be automatically converted into Clarkson Objects.
// Get 20 event objects.
$events = \Clarkson_Core\WordPress_Object\event::get_many( array(
'posts_per_page' => '20'
) );
// Get users with a 'subscriber' role.
$users = \Clarkson_Core\WordPress_Object\Clarkson_User::get_many( array(
'role' => 'subscriber'
) );
// Get 5 terms of the `venue` type.
$venues = \Clarkson_Core\WordPress_Object\venue::get_many( array(
'number' => 5
) );
Every relevant type of object has a get function, in which you can specify an object to retrieve.
// Get an event with ID 5
$event = \Clarkson_Core\WordPress_Object\event::get( 5 );
If the type of the resource you request is not the same as the object you are requesting it on, ClarksonCore will automatically pick the correct object type for you.
// Post ID 6 is of type 'page'
$event = \Clarkson_Core\WordPress_Object\event::get( 6 ); // Notice we are requesting it on the `event` object.
var_dump( get_class( $event ) ); // `Clarkson_Core\WordPress_Object\page`, `Clarkson_Core\WordPress_Object\base_object`, or `Clarkson_Core\WordPress_Object\Clarkson_Object`.
Sometimes you'll have a basic WordPress model available that you want to convert to a Clarkson Object.
To do this, you ca use the utility class \Clarkson_Core\Objects to convert to the correct type.
$event_wp_post = get_post( 5 ); // a WP_Post object.
$event = \Clarkson_Core\Objects::get_instance()->get_object( $event_wp_post ); // A \Clarkson_Core\WordPress_Object\event object.
This conversion type of method is available for all types. See the \Clarkson_Core\Objects reference for these methods.
In some cases you might want more flexibility in determining which object is retrieved.
The following filters are available to manipulate the Clarkson Core object creation process: