Introducing Stripe payment into your PHP projects

For most of WordPress projects, we need to load posts, that’s why I’d like to share with you a useful class to handle this.

## Without a post loader

I’m pretty sure you came across code like this through your WordPress projects :

```php
$query = new WP_Query([
    'post_type' => 'custom_post_type_name',
    'order' => 'ASC',
    'posts_per_page' => 5,
]);
$posts = $query->get_posts();
 
/** making stuff with these posts... */
```

It’s basically the most standard way of retrieving posts, it’s efficient and convenient most of the time.

Now, to spice things a bit, I would like to paginate the results of this query.
So first I’ll have to check if any parameter is set (like page in the url, or directly the `get_query_var('page')` available from WordPress) and then if it’s the case, then I’ll to edit query’s arguments.
I would also like to retrieve my posts by years, then I’ll need another condition and edit query’s arguments…

Well, let’s see how it looks :
```php
$args = [
    'post_type' => 'custom_post_type_name',
    'order' => 'ASC',
    'posts_per_page' => 5,
];
 
if (!empty($_GET['yr'])) {
    $year = (int) $_GET['yr'];
    $args['date_query'] = [[
        'year' => $year,
    ]];
}
 
$currentPage = (int)(get_query_var('page')) ? get_query_var('page') : 1;
 
$args['paged'] = $currentPage;
 
$query = new WP_Query($args);
$posts = $query->get_posts();
 
/** making stuff with these posts... */
```

If this kind of stuff happens in your templates or functions then this will getting out of hand pretty quickly if it needs more customization like adding ACF argument aswell, or any kind of maintenance (by you or others developers).
Also, note that we didn’t even render pagination based on the query results...

Also, if you need to repeat queries like this then it’s even more difficult to maintain through your whole project.

That’s why I’d like to share a very minimalist class to handle these kind of operations.

## With a post loader

First, let’s see how we use it :
```php
<?php
use App\PostLoader;
 
$loader = new PostLoader('custom_post_type_name', get_permalink(get_the_ID()), 5);
$posts = $loader->getPosts();
 
/** making stuff with these posts... */
```

This example is the same as the first, you retrieve the same posts based on the parameters you gave to the constructor.

Let’s see now how to add arguments to our loader :
```php
$loader = new PostLoader('custom_post_type_name', get_permalink(get_the_ID()), 5);
 
if (!empty($_GET['yr'])) {
    $loader->setArgument('date_query', [[
        'year' => (int)$_GET['yr'],
    ]]);
}
 
$posts = $loader->getPosts();
```

We can retrieve every post of the year specified, another benefit that this class offer is the rendering of the pagination, simply call it like this :
```php
echo $loader->getPagination();
```

Which builds for you all the html needed for pagination.
You also need to inject some parameters in the pagination links ? You can render pagination like this aswell :
```php
echo $loader->getPagination(['yr' => (int)$_GET['yr']]);
```

So when you go through pages, you won’t lose any parameters already set.

## PostLoader class

Here’s the class:
```php
<?php

namespace App;
 
use WP_Query;
 
class PostLoader
{
    /** @var string */
    private $postType;
    
    /** @var string */
    private $basePageUrl;
    
    /** @var int */
    private $postsPerPage;
    
    /** @var int */
    private $page;
    
    /** @var int */
    private $totalPosts;
    
    /** @var int */
    private $totalPages;
    
    /** @var array */
    private $params;
    
    /**
     * @param string $postType Post type to retrieve
     * @param string $basePageUrl Url of the page that handles your posts archives
     * @param int $postsPerPage How many posts to retrieve per page
     */
    public function __construct(string $postType, string $basePageUrl, int $postsPerPage)
    {
        $this->postType = $postType;
        $this->basePageUrl = $basePageUrl;
        $this->postsPerPage = $postsPerPage;
        $this->params = [
            'post_type' => $this->postType,
            'posts_per_page' => $this->postsPerPage,
        ];
    }
    
    /**
     * @param int|null $page Specify which page to retrieve if needed, fallback to "page" query var
     * 
     * @return array
     */
    public function getPosts(?int $page = null): array
    {
        if ($page === null) {
            $this->page = (int)(get_query_var('page')) ? get_query_var('page') : 1;
        } else {
            $this->page = $page;
        }
        
        $this->setArgument('paged', $this->page);
 
        $query = new WP_Query($this->getParams());
 
        $this->totalPosts = (int)$query->found_posts;
        $this->totalPages = (int)$query->max_num_pages;
 
        return $query->get_posts();
    }
    
    /**
     * @param array|null $params If parameters needs to be injected inside the link
     * 
     * @return string
     */
    public function getPagination(?array $params = null): string
    {
        $paramsString = '';
 
        if (!empty($params)) {
            $paramsString = '?' . http_build_query($params);
        }
 
        $html = '<ul class="paginationContainer">';
 
        // If we haven't already call the getPosts method then we do it now
        if ($this->totalPages === null) $this->getPosts();
 
        for ($i = 1; $i <= $this->totalPages; $i++) {
            $addedClasses = '';
 
            if ($i === $this->page) {
                $addedClasses .= ' activeItem';
            }
 
            $html .= "
                <li class='paginationItem {$addedClasses}'>
                    <a href='{$this->basePageUrl}{$i}{$paramsString}' class='paginationLink'>{$i}</a>
                </li>
            ";
        }
 
        $html .= '</ul>';
 
        return $html;
    }
    
    /**
     * @param string $key Argument key
     * @param mixed $value Argument value
     * 
     * @return self
     */
    public function setArgument(string $key, $value): self
    {
        $this->params[$key] = $value;
 
        return $this;
    }
    
    /**
     * @return array
     */
    public function getParams(): array
    {
        return $this->params;
    }
}
```

It really aims to stay simple and to evolve or extend depending on project.
As you can see, you can easily edit how pagination is built (you could even use a view if needed), change how things are implemented and add your own logic.

Using an object-oriented approach allow us to easily edit the behaviour of the loader but also add new to it. (with other benefits like being reusable, easier to test, cleaner...)

Aswell, you can note that we can override the page being called with the `getPosts()` method, this is quite useful when you doing [ajax loading](/articles/wordpress-ajax-an-object-oriented-way) and you need to call a precise page through your request. (otherwise it fallback to `get_query_var('page')` if set or first page )

Queries being handled directly from this post loader, this lighten your templates (or functions) and allow you to have a constant and easier api to work with.
(it also encourages you to work with objects ! :D)

I hope you’ll see some uses for this tiny code, it’s totally free to use ! :)

Thanks for reading !

WordPress - A minimalist post loader

Today I’d like to share with you a more object oriented way to handle ajax within WordPress.

## "Classic" Way

I’ve been doing a lot of ajax with WordPress, I’ve done it the “original” way where you put the code in your `functions.php` and it would look like this :
```php
<?php
function add_js_scripts() {
    wp_enqueue_script('script', get_stylesheet_directory_uri().'/js/script.js', array('jquery'), '1.0', true);

    // pass Ajax Url to script.js
    wp_localize_script('script', 'ajaxurl', admin_url('admin-ajax.php'));
}
add_action('wp_enqueue_scripts', 'add_js_scripts');

add_action('wp_ajax_my_action', 'my_action');
add_action('wp_ajax_nopriv_my_action', 'my_action');

function my_action() {
    $param = $_POST['param'];
    echo $param;
    die();
}
```

And then you would put your jQuery ajax this way :
```js
$.ajax({
    url: ajaxurl,
    method: 'POST',
    data: {
        action: 'my_action',
        username: 'Frast',
    },
    success: function (response) {
        console.log(response);
    },
});
```

This approach always worked (and always will, I guess), but we can spot few drawbacks using procedural way, like :
* It's polluting the `functions.php`, what happens when you’ll get 2, 5, 15 ajax actions ? (To avoid this, I’ve always split my actions into different files to stay organized)
* You’ll have to edit a lot of text (function name, your javascript file name maybe, your actions name, ...) in the case scenario where you need to edit your action name
* You’ll repeat a lot of the same code most of the time
* You’ll maybe wrap your code into some conditions if you want to load it only in certains scenarios
* If you have more than one action and so you call `wp_localize_script()` more than once, it just duplicate code, which is not very useful (in ajax case, you’ll always need to bind it to `admin-ajax.php`)
* …

## Going OOP
To simplify all of this, I’ve made a **small** package that you can install with composer :
```
composer require frast/wp-aoo
```
*(It’s about 2 files to be honest)*

Once installed, you can go to your `functions.php` and require your composer autoload like this :
```php
require(__DIR__ . '/vendor/autoload.php');
```

For the next part, I’ll make the assumption that you created a `src/` folder in your theme and inside it you’ll make the class `MyAction` inside another `Ajax/` folder.  
Also, for organization sake, you’ll make another file called `loadAjax.php` in the `src/` folder and require it from the `functions.php` (after the autoload require).  
Finally, you’ll create the js file linked to the ajax action, we’ll call it `MyAction.js`

Your theme directory should look like this:
```
- assets/
    - js/
        - MyAction.js
- src/
    - Ajax/
        - MyAction.php
    - loadAjax.php
- vendor/
    - frast/
    - autoload.php
- functions.php
```

Inside your class `MyAction` the most basic code could be :
```php
<?php
# src/Ajax/MyAction.php

namespace App\Ajax;

use Frast\AjaxHandler;

class MyAction extends AjaxHandler
{
	/** @var array I specify that my js script will need jQuery as a dependency */
	protected $dependencies = [
		'jquery',
	];

	/**
	 * Return the path of the javascript file binded to the action
	 */
	public function getAssetSrc(): string
	{
		return get_stylesheet_directory_uri() . '/assets/js/MyAction.js';
	}

	/**
	 * How the action is going to handle the requests
	 */
	public function treatment(): void
	{
		// Do your stuff here, don't forget to sanitize user inputs in real case scenario
		$username = $_POST['username'];

		// JSON Response sent back
		wp_send_json([
			'message' => "Hello {$username} !",
		], 200);
	}
}
```

Inside `MyAction.js` :
```js
// assets/js/MyAction.js

jQuery(document).ready(function () {
	// console.log(WP_ADMIN_AJAX);
	// console.log(MyActionNonce);

	jQuery.ajax({
		url: WP_ADMIN_AJAX, // This is globally available, it resolves to the admin ajax url
		method: 'POST',
		data: {
			// The action must be the same as the name of your php class
			action: 'MyAction',
			// For security reason, you must specify the nonce created for your php class
			// You can get it by suffixing "Nonce" to your php class, like so
			nonce: MyActionNonce,
			// Then send whatever data you like
			username: 'Stranger',
		},
		success: function (response) {
			console.log(response);
		},
	});
});
```

And finally to load your `MyAction` handler, put this in your `loadAjax.php` :
```php
<?php
# src/loadAjax.php

use Frast\AjaxLoader;
use App\Ajax\MyAction;

// We register our ajax handlers
(new AjaxLoader())
	->register(MyAction::class)
	->load()
;
```

You can try it as is, it should work ! (hopefully :p)  
By the way, don't forget to autoload your `App` namespace (from `src/`) in your `composer.json`, like so :
```
{
    "require": {
        "frast/wp-aoo": "^1.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}
```
And then to refresh the autoload with the command `composer dump-autoload`  
You can find a full demo of the package [here](https://github.com/Mazzzoni/demo-wp-aoo)

## How it works

The class `MyAction` declared two methods :
* `getAssetSrc()` : It returns the path of the js file that the action is binded to
* `treatment()` : It treats the request made on this action

Where you would normally put `wp_ajax_nopriv_my_action` and `wp_ajax_my_action`, `MyAction` inheriting from `Frast\AjaxHandler` will automatically do it for you based on the class name.  
It will also call `wp_enqueue_script()` with the arguments that you defined. (see customization below)

After that we register our class within `loadAjax.php` with :
```php
(new AjaxLoader())
    ->register(MyAction::class)
    ->load()
;
```

This simply register all of the handlers we want and then load them for WordPress to use them. (which will call the `add_action()` and `wp_enqueue_script()` with the config you gave to each handler)

[All the code is available here and is free to use for literally anything](https://github.com/Mazzzoni/wp-aoo)

This is quite a small library so it would’nt be too long to grasp how it works.

## Why would I use this ?

By using this approach you get :
* A clean way to organize your files
* Most of the time files will stay pretty small, but if it grows, your logic will remains inside a well defined class (but keep in mind to stay a bit **SOLID**)
* If another developer have to catch up with your code, he can instantly see what you’ve loaded, which js file you’re querying, …
* You can define concise conditions for loading (see customization below)
* You can define clearly dependencies, version and in_footer if needed
* You could automate even more things, like how the binded javascript file is fetch by extending the `AjaxHandler` class and specify an ajax javascript folder and then automatically fetch a javascript file that has the same name as your php class. That is an example of how you could easily take profit from doing OOP way
* ...

It also encourages you to go a bit more object oriented inside WordPress development since a lot of tutorials and way of doing are more procedural-like.

## Customization

Sometimes, you would like to load an handler only if certains conditions are met.  
You can do that by declaring this in your handler class :
```php
/**
 * Based on the return value, it will enable or not the ajax action
 */
public function conditions(): bool
{
	// You can also access WordPress functions from here
	$canLoad = is_home();

	return $canLoad;
}
```

Based on the return value, it will load or not your handler, saving some computation time and a browser request. (since it won’t `wp_enqueue_script()` your js script)

Also, since you can specify optionnals arguments to `wp_enqueue_script()`, you can redefine them with :
```php
/** @var array */
protected $dependencies = [];

/** @var string|bool|null */
protected $version = false;

/** @var bool */
protected $inFooter = true;
```

Inside your handler class.

You can basically override anything from your handler class if needed.

## Conclusion

This package can help you to better organize your files and logic on larger project (even if I use it on small project aswell) and this is quite valuable when you have to maintain projects !

I've also made a demo project that is available [here](https://github.com/Mazzzoni/demo-wp-aoo) which contains few examples of how you can profit from this package.

I hope that you can find any utility to this **quite small** package and aswell that it will motivates you to go a bit more into OOP if it's not already the case ! :)

François Steinel - Web Developer

Latest articles

Introducing Stripe payment into your PHP projects

WordPress - A minimalist post loader

WordPress Ajax - An object oriented way