Eloquent
Forme makes the built in WordPress objects available as Eloquent Models, so you can take full advantage of its easy to use syntax instead of trying to remember WordPress' arcane incantations.
We use a similar approach to wp-eloquent
Built-in WordPress Models
- Post
- Comment
- Post Meta
- User
- User Meta
use Forme\Framework\Models\Post as Post;
dump(Post::all()); //returns only posts with WordPress post_type "post"
Posts
You can grab any standard WordPress post properties as you would expect:
echo $post->post_type;
echo $post->post_title;
echo $post->post_name;
echo $post->ID;
There are a couple of preset accessors to provide syntactic sugar and get rid of some of the Hungarian notation redundancy.
// the following also works
echo $post->type; // alias of post_type
echo $post->title; // alias of post_title
echo $post->slug; // alias of post_name
echo $post->content // alias of post_content
We've also wrapped get_permalink()
into a more concise url
property.
echo $post->url;
You can also grab meta from posts or users using magic properties in the form key_name_meta
, for example:
echo $user->first_name_meta; // the meta_value of the user's first_name meta
echo $post->_wp_page_template_meta; // the meta_value of the post's _wp_page_template
You'll get back a string, so you'll need to take care of converting serialised values yourself for example.
For some use cases it's easier to use internal WordPress functions, although you can of course wrap them in Model methods if you want to simplify the syntax.
Custom Post Types
You can extend Post
and add the CustomPostable
trait to access Custom Post Types too. You can add the static $postType
property to point it in the right direction, otherwise it will try to guess by taking the snake_case
version of the class name.
namespace App\Models;
use Forme\Framework\Models\CustomPostable;
use Forme\Framework\Models\Post;
final class FooBar extends Post
{
use CustomPostable;
/** @var string */
protected static $postType = 'foo_bar';
}
Filter Post
by post_status
and post_type
use Forme\Framework\Models\Post as Post;
dump(Post::type('page')->get()->toArray()); // get pages
dump(Post::status('publish')->get()->toArray()); // get posts with publish status
dump(Post::type('page')->status('publish')->get()->toArray()); // get pages with publish status
Inserting and updating Posts
You can call the usual Eloquent methods to update posts programmatically.
$post = Post::find(123);
$post->post_title = "Foo";
$post->post_content = "Lorem Ipsum";
$post->save();
WARNING
Inserting & updating WordPress entities with Eloquent should work as you would expect, but you might sometimes need to ensure that specific properties are added manually, especially since hooks will tend to be ignored. You can always fall back to standard WordPress functions if you get unexpected results.
ACF Fields
We're looking at implementing some kind of core pattern for ACF fields and relations, but for the time being, we recommend setting up accessors and mutators.
public function getFooAttribute(): ?int
{
// NB: we're casting to int and coercing falsy values to null here
// you may or may not want this, it's just to illustrate that you may need to consider typing
// since get_field returns are somewhat loose
return (int) get_field('foo', $this->ID) ?: null;
}
public function setFooAttribute(int $value): void
{
update_field('foo', $value, $this->ID);
}
WARNING
If you use the above pattern, you need to be aware of a couple of gotchas.
- If you're calling these on a new post, you'll have to
save
it first so that the id exists. - The mutator saves the acf field to the db immediately, so you won't need to call
save
after setting the property.
Post Hierarchy
You can grab a post's direct children using the attribute.
// this will give you a collection of posts
dump($post->children);
You can also check if a post has any children with the hasChildren
method.
// bool result
dump($post->hasChildren());
Code Generation
You can create a new post type model via the cli:
forme make model FooBar
This will make a new post type model class YourNameSpace\YourApp\Models\FooBar
for the foo-bar
post type.
You probably won't need this that often since models are created when you make a post type via the cli in any case.
Custom Tables and Entities
If you've created custom tables e.g. using migrations (i.e. not custom post types), you can extend Illuminate\Database\Eloquent\Model
directly to create your model class.
// app/Models/FooBar.php
declare(strict_types=1);
namespace YourNameSpace\Yourapp\Models;
use Illuminate\Database\Eloquent\Model;
class FooBar extends Model
{
}
TIP
You don't need to worry about including the wp table prefix in your definition. Forme uses Capsule under the hood and that's already all set up for you during the boot process!