Helpers

Helpers include a list of functions and full classes that help you simplify your code and remove the tedium of having to write code for popular problems. Below are the helpers that the Dragon Framework provides for you.

Functions

nonce()

nonce()

While this is created for use as a blade directive, you may also use it to display the hidden form field containing the nonce code generated by WordPress.

<p></p>

Example Output:

<p><input name="dragonfw_dragonapp_nonce" value="d7cccc2187" type="hidden" /></p>

send_cookie()

send_cookie(\Symfony\Component\HttpFoundation\Cookie $cookie)

This will queue a cookie created with Symfony's Cookie object to be sent to the browser. Unlike setcookie() from PHP, this will take the cookie object from the Request, even one virtualized by Dragon Framework, and send that to the browser.

image()

image(string $filename)

While this is created for use as a blade directive, you can still use it outside of blade. Displays the URL for the image specified in $filename located in the resources/assets/img directory, either in your app or if that doesn't exist, then the one in the framework.

<p><img src="" /></p>

Example Output:

<p><img src="/wp-content/plugins/dragonapp/resources/assets/img/dragon.png" /></p>

css()

css(string $filename)

Displays the URL for the CSS file specified in $filename located in the resources/assets/css directory, either in your app or if that doesn't exist, then the one in the framework.

js()

js(string $filename)

Displays the URL for the JS file specified in $filename located in the resources/assets/js directory, either in your app or if that doesn't exist, then the one in the framework.

Database Models

Dragon Framework comes with Eloquent ORM models for each of the default WordPress tables. These are their methods.

Dragon\Database\Models\Comment

parent()

public function parent() : HasOne

Access the parent comment (if any).

user()

public function user() : HasOne

Access the user that wrote the comment.

post()

public function post() : HasOne

Access the post on which the comment was left.

Dragon\Database\Models\CommentMeta

comment()

public function comment() : HasOne

Access the parent comment for which this meta data belongs.

Dragon\Database\Models\Link

owner()

public function owner() : HasOne

Access the link owner/user.

Dragon\Database\Models\Option

No extra methods.

Dragon\Database\Models\Post

author()

public function author() : HasOne

Access the post author.

parent()

public function parent() : HasOne

Access the parent post.

taxonomies()

public function taxonomies() : BelongsToMany

Access the list of taxonomies assigned to this post. (Done through the Dragon\Database\Models\TermRelationship Pivot table.)

Dragon\Database\Models\PostMeta

post()

public function post() : HasOne

Access the post to which this meta data belongs.

Dragon\Database\Models\Term

No extra methods.

Dragon\Database\Models\TermMeta

post()

public function term() : HasOne

Access the term on which this meta data belongs.

Dragon\Database\Models\TermTaxonomy

term()

public function term() : HasOne

Access the term for the taxonomy.

parent()

public function parent() : HasOne

Access the parent taxonomy.

posts()

public function posts() : BelongsToMany

Access the posts associated with this taxonomy. (Done through the Dragon\Database\Models\TermRelationship Pivot table.)

Dragon\Database\Models\User

No extra methods.

Dragon\Database\Models\UserMeta

user()

public function user() : HasOne

Access the user to whom this meta data belongs.

Classes and Objects

Dragon\Admin\Notice

error()

public static function error(string $message)

This will queue an error (red) admin notice using the WordPress function wp_admin_notice.

success()

public static function success(string $message)

This will queue a success (green) admin notice using the WordPress function wp_admin_notice.

makeNotice()

public static function makeNotice(string $type, string $message)

This will queue a notice of type $type which displays $message to the admin user.

Dragon\Assets\Asset

dir()

public static function dir(string $extra = "") : ?string

This will return the HTML-ready directory for an item in resources/assets when $extra contains a valid filename or path. If $extra is empty, then it will return the path to resources/assets. First the method will look for the file in your app/resources/assets directory, and if it doesn't exist, it will look for it in the Dragon Framework directory.

Dragon\Core\Config

getBaseDir()

public static function getBaseDir() : string

Get the full path to your plugin directory. (Ex. /var/www/wordpress/wp-contents/plugins/dragonapp and no trailing /)

getPluginDirName()

public static function getPluginDirName() : string

Get the name of the directory in which your plugin resides. (Ex. dragonapp)

getLoaderFilename()

public static function getLoaderFilename() : string

Get the name of the file that loaded the dragon framework. (Ex. /var/www/wordpress/wp-contents/plugins/dragonapp/loader.php)

prefix()

public static function prefix() : string

Get the prefix used for namespacing.

get()

public static function get(string $key, $default = null)

While config($path) is the preferred way to load config files, sometimes you might need to load a file when the application hasn't finished loading. This method will load your config file for you from app/config.

Dragon\Database\Option

A wrapper class to handle namespaced get_option update_option and delete_option.

get()

public static function get(string $key, $default = null)

Get the namespaced $key value through get_option or return the default.

set()

public static function set(string $key, $value)

Set the $value to the namespaced $key using update_option.

delete()

public static function delete(string $key)

Delete the option using the namespaced $key through delete_option.

Dragon\Posts\Post

getContent()

public static function getContent($postId) : string

Gets the post content. This is a wrapper for get_post()->post_content and so it will accept the following for $postId: int, WP_Post, null.

setPostMeta()

public static function setPostMeta(int $postId, string $key, $value)

Sets the post meta. This is a wrapper for update_post_meta().

getPostMeta()

public static function getPostMeta(int $postId, string $key, $default = null)

Gets the post meta, or returns a $default. Relies on get_post_meta().

Dragon\Support\Bot

isBot()

public static function isBot($userAgent = null)

Extremely basic bot detection method that simply checks $userAgent against a list of known bot agents.

Dragon\Support\Csv

Rudimentary tooling for working with CSV files.

__construct()

public function __construct(?string $filename = null)

If you pass a CSV filename to the constructor, it'll parse the file for you and set the public $headers = []; and public $rows = []; properties for you. You can always set them later if you prefer, so that you can call download().

isCsv()

public function isCsv() : bool

Checks the mime type of the filename passed to the constructor if you chose to pass it. If it's one of the known CSV mime types, then it'll return true, otherwise false.

download()

public function download(string $filename)

Push the CSV file to the browser using the filename $filename as the default filename the filename save box will use as the filename. (Ahem... I need coffee... :) )

Dragon\Support\Image

getMediaImageUrlById()

public static function getMediaImageUrlById(int $id, $size = "thumbnail") : ?string

Returns the URL to the media gallery image for the specified attachment $id, and WordPress-defined $size.

getPathForMediaImageById()

public static function getPathForMediaImageById(int $id) : ?string

Returns the HTML-ready image path for the attachment with ID $id. (Wrapper for wp_get_original_image_path())

Dragon\Support\Plugin

getData()

public static function getData() : ?string

Returns the metadata specified in the plugin's loader file. (That's the stuff written in the multiline comment / docblock.) It's just raw text without the comment stars and whatnot. However, if it's malformed, the method will return null.

Dragon\Support\Url

isRestRequest()

public static function isRestRequest() : bool

Returns the value of REST_REQUEST or false if it's not defined.

isUrl()

public static function isUrl(string $text, string $protocolStartsWith = 'http') : bool

Checks if the contents of $text is a URL by seeing if it starts with $protocolStartsWith.

getBySlug()

public static function getBySlug(string $page, array $additionalQuery = []) : string

Get the URL of a WordPress page identified by the $page slug. You can add extra query parameters with $additionalQuery by setting it to a key-value pair of query parameters.

getProductBySlug()

public static function getProductBySlug(string $page) : ?string

Get the URL of a WooCommerce product identified by the $page slug.

getAdminMenuLink()

public static function getAdminMenuLink($slug, array $additionalQuery = []) : string

Get the URL of a WP Admin page by passing the page $slug. You can add extra query parameters with $additionalQuery by setting it to a key-value pair of query parameters.

getCurrentUrl()

public static function getCurrentUrl(array $appendedQuery = []) : string

Get the URL of the current page. You can add extra query parameters with $additionalQuery by setting it to a key-value pair of query parameters.

Dragon\Support\User

isLoggedIn()

public static function isLoggedIn() : bool

Returns true for logged in, or false for not logged in.

get()

public static function get(?int $userId = null)

Returns the WP_User object for the user specified by $userId or if no $userId is passed, then it'll be a WP_User object for the current user.

logout()

public static function logout()

Logs the user out, and returns them to the wp_login_url().

getUserId()

public static function getUserId() : int

Gets the user ID for the current user. It relies on the WP_User object from User::get() behind the scenes.

getUserEmail()

public static function getUserEmail(?int $userId = null) : string

Gets the email for the user specified by $userId or the current user if not passed. It relies on the WP_User object from User::get() behind the scenes.

getUsername()

public static function getUsername(?int $userId = null) : string

Gets the username for the user specified by $userId or the current user if not passed. It relies on the WP_User object from User::get() behind the scenes.

isAdmin()

public static function isAdmin(?int $userId = null) : bool

Checks if the user specified by $userId (or the current user if not passed) has the administrator role. It relies on the WP_User object from User::get() behind the scenes.

can()

public static function can(string $capability, ?int $userId = null) : bool

Checks if the user specified by $userId (or the current user if not passed) has the given $capability assigned to them. It relies on the WP_User object from User::get() behind the scenes.

getRole()

public static function getRole(?int $userId = null) : ?string

Gets the first role assigned to the user specified by $userId or the current user if not passed. It relies on the WP_User object from User::get() behind the scenes.

hasRole()

public static function hasRole(string $role, ?int $userId = null) : bool

Checks if the user specified by $userId (or the current user if not passed) has the given $role assigned to them. It relies on the WP_User object from User::get() behind the scenes.

setRole()

public static function setRole(int $userId, string $role)

Assigns the specified $role to the user specified by $userId. It relies on the WP_User object from User::get() behind the scenes.

getRoles()

public static function getRoles(?int $userId = null) : array

Gets the array of roles assigned to the user specified by $userId or the current user if not passed. It relies on the WP_User object from User::get() behind the scenes.

getCapabilities()

public static function getCapabilities(?int $userId = null) : array

Gets the array of capabilities assigned to the user specified by $userId or the current user if not passed. It relies on the WP_User object from User::get() behind the scenes.

getMeta()

public static function getMeta(?string $key = null, $default = null, ?int $userId = null)

Gets user meta data for the user specified by $userId or the current user if not passed. It relies on the WP_User object from User::get() behind the scenes. If the meta data doesn't exist, it'll return $default.

getAllMeta()

public static function getAllMeta(int $userId) : array

Gets the array of all meta data for the user specified by $userId. (Wrapper for get_user_meta().)

setMeta()

public static function setMeta(string $key, $value, ?int $userId = null)

Sets user meta data for the user specified by $userId or the current user if not passed.

deleteMeta()

public static function deleteMeta(string $key, ?int $userId = null)

Deletes user meta data for the user specified by $userId or the current user if not passed.

getUserIds()

public static function getUserIds(array $args = []) : array

Returns a list of all user IDs in the system that match the $args, or all users in the system if not passed. (Relies on WP function get_users() to handle the $args.

redirectIfNotLoggedIn()

public static function redirectIfNotLoggedIn()

If the current user isn't logged in, then call auth_redirect().

getUserOption()

public static function getUserOption(string $key, $default = null, ?int $userId = null)

This will get the value for the $key (namespaced behind the scenes) for the given $userId (or the current user if not passed). It will return $default if the value isn't found through get_option().

setUserOption()

public static function setUserOption(string $key, $data, ?int $userId = null)

This will set the value for the $key (namespaced behind the scenes) for the given $userId (or the current user if not passed).

loginAs()

public static function loginAs(int $userId)

This will permanently log the current user in as another user ($userId) until the user running loginAs() logs out.

register()

public static function register(string $username, string $password, string $email) : int|WP_Error

Register a new user user through wp_create_user(). The $password is sent to this method unencrypted.

Dragon\Support\Util

namespaced()

public static function namespaced(string $key) : string

Returns the namespaced version of $key.

unnamespaced()

public static function unnamespaced(string $key) : string

Pass the namespaced $key in, and it will return the original unnamespaced key.

onlyDigits()

public static function onlyDigits(string $text) : string

Returns only the digits contained in $text, in the order in which the digits appear in $text, using the PHP function ctype_digit().

isEmail()

public static function isEmail(string $email) : bool

Checks if $email contains a valid email address according to WordPress' rules, and then with PHP's filter_var($email, FILTER_VALIDATE_EMAIL).

phoneFormat()

public static function phoneFormat(?string $phoneNumber, string $region = 'US', int $format = PhoneNumberFormat::E164) : ?string

Uses Google's libphonenumber library to parse the phone number into the desired format.

nth()

public static function nth(float $number) : ?string

Pass in a $number such as 1, and get back the ordinal value. (Ex. first)

moneyFormat()

public static function moneyFormat(?float $number, string $currency = "USD") : ?string

Pass in a $number and optionally a three-character (ISO 4217) $currency code, and receive the resulting text to display the money to the user. (Ex. $1.00, CA$1.00, RUB 1.00, etc.)

Form Fields

abstract class Dragon\Http\Form\Field

All form fields in Dragon Framework rely on this abstract class. You're welcome to extend it as well. All setter methods return the field so you can keep chaining them together as needed.

make()

public static function make(string $name) : static

Creates a new instance of the field and sets the HTML name to $name, then returns the instance for chaining.

attributes()

public function attributes(array $attributes) : static

Sets the array of HTML attributes as a key-pair as meta data. (Ex. ['id' => 'my-field'])

label()

public function label(string $label) : static

Sets the label text meta data associated with the field.

value()

public function value(?string $value) : static

Sets the HTML value attribute meta data to $value.

required()

public function required(bool $isRequired = true) : static

Sets the field meta data to mark the field as required or optional.

required()

public function required(bool $isRequired = true) : static

Sets the field meta data to mark the field as required or optional.

encrypted()

public function encrypted(bool $isEncrypted = true) : static

Sets the field meta data to mark the field as encrypted or plain text.

readOnly()

public function readOnly(bool $isReadOnly = true) : static

Sets the field meta data to mark the field as read only.

isReadOnly()

public function isReadOnly() : bool

Gets the boolean value set through readOnly().

getName()

public function getName() : string

Gets the name set while using make().

getValue()

public function getValue() : ?string

Gets the value set by value(). If the field is marked encrypted() then it will try and decrypt it using app('encrypter')->decrypt().

getLabel()

public function getLabel() : ?string

Gets the label meta data associated with the field.

getAttributes()

public function getAttributes() : array

Gets the HTML attributes array meta data associated with the field.

isRequired()

public function isRequired() : bool

Gets the boolean value set through required().

isEncrypted()

public function isEncrypted() : bool

Gets the boolean value set through encrypted().

render()

public function render() : string

This will check if the field is read only or not. If it's in read only mode, it will return the result of $this->getValue(). If it's not in read only mode, it will call the $this->toHtml() method.

toHtml()

abstract protected function toHtml() : string

This is an abstract method that must be implemented by each subclass. When called, it will turn the object into the respective HTML code for the object.

Dragon\Http\Form\Select

The Select class extends Dragon\Http\Form\Field, and all of its methods are available for use.

options()

public function options(array $options) : static

Sets the list of option items for the select box. The $options array is a key-value paid with values as keys, and display text as values.

Dragon\Http\Form\Textarea

The Textarea class extends Dragon\Http\Form\Field, and all of its methods are available for use.

Dragon\Http\Form\Textbox

The Textbox class extends Dragon\Http\Form\Field, and all of its methods are available for use.

type()

public function type(string $type) : static

Sets the type if input box. $type could be hidden, number, text (default), date, email, or whatever else you might find useful.

getType()

public function getType() : string

Gets the type set by type().