Day 10: Introduction To WordPress & PHP DocString Comments

What is WordPress?

WordPress is a free and open-source web content management software (CMS) that can be downloaded and installed on one’s own server. With WordPress, you can create various types of websites, from a simple personal blog or portfolio site to a full-fledged eCommerce website or a news magazine serving billions of web pages each month.

Here are some common use cases:

• Blogging
• Business Websites
• E-commerce
• Portfolios
• Educational Websites
• Membership Sites
• Forums and Communities
• News and Magazines
• Nonprofit and Charity Sites
• Personal Websites and Resumes
• Multilingual Sites
• Directories and Listings

Here are some short notes on the technical usage of WordPress:

1. Themes and Templates: WordPress uses themes to control the appearance and layout of a site. Themes consist of template files written in PHP, HTML, CSS, and JavaScript. Developers can create custom themes or use and modify existing ones to meet specific design requirements.
2. Plugins: Plugins extend the functionality of WordPress. They can be used to add features like SEO optimization, security enhancements, e-commerce capabilities, and more. Developers can write custom plugins to add bespoke features.
3. Custom Post Types: Beyond the default posts and pages, WordPress allows the creation of custom post types for different kinds of content, such as portfolios, testimonials, and products. This is done using the register_post_type function.
4. Custom Taxonomies: To organize content, WordPress supports custom taxonomies, which can be used to create custom categories and tags for different content types. This is done using the register_taxonomy function.
5. REST API: WordPress includes a REST API that allows developers to interact with site data (such as posts, pages, and users) via JSON. This is useful for building custom front-end interfaces or integrating with other applications.
6. Hooks: Actions and Filters: WordPress provides a system of hooks, including actions and filters, that allow developers to modify or extend the functionality of WordPress without modifying core files. Actions are used to trigger events, and filters are used to modify data.
7. Shortcodes: Shortcodes are small code snippets enclosed in square brackets that can be used within posts and pages to add dynamic content. Developers can create custom shortcodes for various purposes, such as embedding forms or displaying custom data.
8. Multisite: WordPress Multisite is a feature that allows the creation of a network of sites under a single WordPress installation. Each site in the network can have its own themes and plugins, but they share a common user base and database.
9. User Roles and Capabilities: WordPress has a robust user role and capability system that controls what different users can do on the site. Custom roles and capabilities can be created to fine-tune access and permissions.
10. Database Management: WordPress uses MySQL or MariaDB as its database management system. Developers interact with the database using WordPress’s global $wpdb object or higher-level functions for querying and manipulating data.
11. WP-CLI: WP-CLI is a command-line interface for WordPress that allows developers to manage their WordPress sites from the terminal. Tasks like updating plugins, managing users, and configuring settings can be automated using WP-CLI commands.
12. Custom Fields and Meta Boxes: Custom fields and meta boxes allow for the addition of custom metadata to posts, pages, and custom post types. This is useful for storing additional information, such as product details or author bios.
13. Localization and Internationalization: WordPress supports the translation of themes and plugins into different languages. Developers use functions like __() and _e() to make strings translatable and create .pot files for translation.

Here are short notes on the basic administration of WordPress:

1. Dashboard: Central hub for managing site content, settings, and appearance.
2. Posts: Create and manage blog entries; categorize and tag for organization.
3. Pages: Static content such as “About” and “Contact” pages.
4. Media Library: Upload and manage images, videos, and other media files.
5. Comments: Moderate and respond to comments left by visitors.
6. Appearance: Customize themes, menus, and widgets to control site layout and design.
7. Plugins: Install and manage plugins to extend site functionality.
8. Users: Manage user accounts and roles; control access levels.
9. Settings: Configure site-wide settings including general, writing, reading, discussion, media, and permalinks.
10. Updates: Keep WordPress core, themes, and plugins updated for security and new features.

WordPress Themes

1. Purpose: Themes control the visual appearance and layout of a WordPress site, including colors, fonts, and overall design.
2. Installation: Themes can be installed from the WordPress Theme Directory or uploaded manually. Navigate to Appearance > Themes in the dashboard to manage them.
3. Customization: Themes often come with customization options via the WordPress Customizer (Appearance > Customize), allowing users to modify site identity, colors, menus, and more without coding.
4. Child Themes: Child themes inherit the functionality of a parent theme and allow for modifications without altering the parent theme’s files, ensuring updates to the parent theme do not overwrite customizations.
5. Template Files: Themes are made up of template files written in PHP, such as header.php, footer.php, and single.php, which control the structure of different parts of the site.

WordPress Plugins

1. Purpose: Plugins extend the functionality of a WordPress site, adding features such as SEO tools, contact forms, e-commerce capabilities, and security enhancements.
2. Installation: Plugins can be installed from the WordPress Plugin Directory or uploaded manually. Navigate to Plugins > Add New in the dashboard to manage them.
3. Activation and Deactivation: Once installed, plugins need to be activated to start functioning. They can also be deactivated without uninstalling, useful for troubleshooting.
4. Customization: Some plugins provide settings pages for configuration, accessible from the dashboard menu. Advanced users can extend or customize plugin functionality via hooks and filters.
5. Performance: While plugins add valuable features, excessive or poorly-coded plugins can slow down a site. It’s important to install only necessary plugins and regularly update them for optimal performance and security.

WordPress: Shortcodes

1. Definition: Shortcodes are small code snippets enclosed in square brackets (e.g., [shortcode]) that allow users to insert dynamic content or functionality into posts, pages, or widgets without writing full code.
2. Usage: Shortcodes simplify the addition of complex elements such as forms, galleries, and custom content. For example, a shortcode might be used to embed a contact form or display recent posts.
3. Creation: Developers can create custom shortcodes using the add_shortcode() function in WordPress. Shortcodes are defined by creating a callback function that generates the desired output.
4. Parameters: Shortcodes can accept parameters to customize their output. These are included within the shortcode tags (e.g., ).
5. Embedding: To use a shortcode, simply insert it into the content editor where the shortcode should appear. WordPress processes it and replaces it with the appropriate output when the content is displayed.
6. Examples: Common default shortcodes include for displaying image galleries and for embedding audio files. Plugins and themes often provide their own shortcodes for additional functionality.

PHP: Comments & DocStrings

What is a DocBlock?

A DocBlock is a piece of documentation in your source code that informs you what the function of a certain class, method or other Structural Element is.

What can be documented in your source code?

Before we discuss what a DocBlock looks like, let’s first zoom in on what you can document with them. phpDocumentor follows the PHPDoc definition and recognizes the following Structural Elements :

• Function
• Constant
• Class
• Interface
• Trait
• Class constant
• Property
• Method

What are DocComments?

A DocComment starts with a forward slash and two asterisks (/** ), which is similar to how you start a multiline comment but with an additional asterisk, and ends with an asterisk and forward slash (*/ ). DocComments may be a single line in size but may also span multiple lines, in which case each line must start with an asterisk. It is customary, and recommended, to align the asterisks vertically when spanning multiple lines.

So, a single line DocComment looks like this:

/** This is a single line DocComment. */

And a multiline DocComment looks like this:

/**
 * This is a multi-line DocComment.
 */

PHPDoc

Something a little more extensive is the PHPDoc DSL. Inside DocComments phpDocumentor, and many other tools with it, expect to find a block of text that matches the PHPDoc Standard.

Commonly a piece of PHPDoc consists of the following three parts in order of appearance:

Summary
A short piece of text, usually one line, providing the basic function of the associated element.
Description
An optional longer piece of text providing more details on the associated element’s function. This is very useful when working with a complex element.
A series of tags
These provide additional information in a structured manner. With these tags you can link to other elements, provide type information for properties and arguments, and more.

Summary

The summary is a short but effective overview of an element; you can compare it to a slogan or headline.

With an empty whiteline:

/**
 * This is a summary
 *
 * This is a description
 */

Or by adding a period followed by a new-line:

/**
 * This is a summary.
 * This is a description
 */

Description

A description can be a long text with an elaborate explanation what the associated element does. The description is optional , as there are many elements that are so straightforward that they do not need a length explanation.

Even worse : proper methods are often so simple that a description could be considered overkill!

Tags

Tags are a type of specialized information (meta-data) about the associated element. At the time of writing of this guide PHPDoc counts twenty-eight (28) types of tags.

A tag always starts on a new line with an at-sign (@) followed by the name of the tag. Between the start of the line and the tag’s name (including at-sign) there may be one or more spaces or tabs.

/**
 * @source
 */

In addition to their name each tag may have arguments that can provide additional context specific for that tag. The most common example of this is the @param tag, with which the argument of a method or function is documented:

/**
 * @param string $argument1 This is the description.
 */

List of tags

Tag	Element	Description
api	Methods	declares that elements are suitable for consumption by third parties.
author	Any	documents the author of the associated element.
category	File, Class	groups a series of packages together.
copyright	Any	documents the copyright information for the associated element.
deprecated	Any	indicates that the associated element is deprecated and can be removed in a future version.
example	Any	shows the code of a specified example file or, optionally, just a portion of it.
filesource	File	includes the source of the current file for use in the output.
global	Variable	informs phpDocumentor of a global variable or its usage.
ignore	Any	tells phpDocumentor that the associated element is not to be included in the documentation.
internal	Any	denotes that the associated elements is internal to this application or library and hides it by default.
license	File, Class	indicates which license is applicable for the associated element.
link	Any	indicates a relation between the associated element and a page of a website.
method	Class	allows a class to know which ‘magic’ methods are callable.
package	File, Class	categorizes the associated element into a logical grouping or subdivision.
param	Method, Function	documents a single argument of a function or method.
property	Class	allows a class to know which ‘magic’ properties are present.
property-read	Class	allows a class to know which ‘magic’ properties are present that are read-only.
property-write	Class	allows a class to know which ‘magic’ properties are present that are write-only.
return	Method, Function	documents the return value of functions or methods.
see	Any	indicates a reference from the associated element to a website or other elements.
since	Any	indicates at which version the associated element became available.
source	Any, except File	shows the source code of the associated element.
subpackage	File, Class	categorizes the associated element into a logical grouping or subdivision.
throws	Method, Function	indicates whether the associated element could throw a specific type of exception.
todo	Any	indicates whether any development activity should still be executed on the associated element.
uses	Any	indicates a reference to (and from) a single associated element.
var	Properties
version	Any	indicates the current version of Structural Elements.

Annotations

An Annotation is a specialized form of tag that not only documents a specific aspect of the associated element but also influences the way the application behaves.

Annotations come in various forms, many look exactly like normal tags but some have a more complicated syntax:

/**
 * @ORM\Entity(repositoryClass="MyProject\UserRepository")
 */

In the example above we demonstrate how you define that a class represents a database entity in Doctrine; as you can see the tag name is separated into two parts, a namespace and the actual annotation name,

Examples

File DocComment:

/**
 * REST API: WP_REST_Posts_Controller class
 *
 * @package WordPress
 * @subpackage REST_API
 * @since 4.7.0
 */

Class DocComment

/**
 * Core class to access posts via the REST API.
 *
 * @since 4.7.0
 *
 * @see WP_REST_Controller
 */

Function DocComment

/**
	 * Whether the controller supports batching.
	 *
	 * @since 5.9.0
	 * @var array
*/
protected $allow_batch = array( 'v1' => true );

Thanks for reading this…

By ~ Leaveitblank (Mayank Tripathi)