Permalink
Browse files

Introduce Admin_Page interface.

  • Loading branch information...
felixarntz committed Jan 14, 2018
1 parent 3d1549c commit 8f4f979ee4318570557d0e855fe06977ce57f9ec
Showing with 67 additions and 0 deletions.
  1. +67 −0 src/Admin_Page.php
@@ -0,0 +1,67 @@
<?php
/**
* Admin_Page interface
*
* @package Leaves_And_Love\OOP_Admin_Pages
* @since 1.0.0
*/
namespace Leaves_And_Love\OOP_Admin_Pages;

This comment has been minimized.

@felixarntz

felixarntz Jan 19, 2018

Owner

Always use namespaces for your code, unless you need to support PHP 5.2 (for whatever reason). A good convention for a project's base namespace is to use the author/organization name as first part and the project name as second part. All sub-namespaces should then reflect the directory structure of the project.

/**
* Interface representing an admin page.
*
* @since 1.0.0
*/
interface Admin_Page {
/**
* Gets the slug of the admin page.
*
* @since 1.0.0
*
* @return string Admin page slug.
*/
public function get_slug() : string;
/**
* Gets the title of the admin page.
*
* @since 1.0.0
*
* @return string Admin page title.
*/
public function get_title() : string;
/**
* Gets the URL of the admin page.
*
* @since 1.0.0
*
* @return string Admin page URL.
*/
public function get_url() : string;
/**
* Registers the admin page within the environment.
*
* @since 1.0.0
*/
public function register();
/**
* Initializes the admin page on pageload.
*
* This method must be called before any output is printed.
*
* @since 1.0.0
*/
public function initialize();
/**
* Renders the admin page content.
*
* @since 1.0.0
*/
public function render();
}

1 comment on commit 8f4f979

@felixarntz

This comment has been minimized.

Owner

felixarntz commented on 8f4f979 Jan 19, 2018

Why an interface?

While an interface cannot contain any actual functionality, it defines the API by exposing what should be publicly available. Nothing should be public that is not part of the API. Anything that is public must not change unless it's in a major update. → WordPress core does not use interfaces, hence does not define its APIs. Therefore every public method and every function is part of the API. That is why it's so hard to make changes without breaking backward-compatibility and without hacking around a problem.

Another reason for using interfaces is the Dependency Inversion Principle (the D in SOLID). More on that in a later commit.

Where are the other parameters handled, like capability and such?

In order to make code reusable, one should try to define interfaces in the most basic way possible. While it would be fine to define an interface WordPress_Admin_Page and have it contain a capability property, capabilities are specific to WordPress admin pages. Ask yourself: What is absolutely necessary for what I'm trying to model? There are of course no right and wrong answers here. It entirely depends on what you consider essential and how far you are aiming to abstract. For this project, at its simplest foundation, an admin page has an identifier, a title, a URL and callbacks for rendering and initializing. Everything that is more specific will be part of individual implementations. This is what makes this interface reusable across projects even outside of WordPress.

Please sign in to comment.