🛠️ Weekend Project: PHP & WordPress

The Brief & Why It's Structured This Way

Creative professionals — photographers, designers, illustrators — need a clean, self-managed way to show their work. A generic blog theme buries images in a river of posts; a page builder locks their content inside proprietary shortcodes. Your job is to give them something portable and maintainable: their projects live in the database as first-class content, and any theme can render them.

That last sentence is the whole design principle of this project, and it's the single most important WordPress lesson in the module:

We'll work in three milestones, and each ends with something you can actually see working. That's deliberate: shipping a small working slice beats a big broken one, and it keeps motivation high across a two-day sprint.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );   // writes to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false );

Architecture: Theme vs. Plugin

Here is how responsibility splits across the two pieces you'll build. Notice the flow of ownership: the plugin owns the data, the theme owns the pixels, and they meet at a thin, well-defined boundary of template functions.

A quick way to sanity-check any feature you're about to build: ask "if the user switched themes tomorrow, should this still exist?" If yes, it's plugin work. If no, it's theme work.

The Milestone Map

Three milestones, each independently demoable. Don't move on until the current one works in the browser.

Milestone 1 — Scaffold the Plugin

Create wp-content/plugins/portfolio-showcase/portfolio-showcase.php. The header comment is what makes WordPress recognize it as a plugin; the WPINC guard blocks anyone from loading the file directly.

<?php
/**
 * Plugin Name:       Portfolio Showcase
 * Description:       Custom post type, taxonomy, and shortcode for a creative portfolio.
 * Version:           1.0.0
 * Requires PHP:      8.2
 * Requires at least: 6.4
 * Author:            Your Name
 * License:           GPL-2.0-or-later
 * Text Domain:       portfolio-showcase
 */

// Abort if accessed directly.
if ( ! defined( 'WPINC' ) ) {
    die;
}

define( 'PORTFOLIO_SHOWCASE_VERSION', '1.0.0' );

Now register the post type and taxonomy. We hook both to init. Setting 'show_in_rest' => true is what makes the block editor (Gutenberg) work for your custom content — skip it and editors get the old classic editor by surprise.

/**
 * Register the "portfolio" custom post type.
 */
function portfolio_showcase_register_cpt() {
    $labels = array(
        'name'          => __( 'Portfolio Items', 'portfolio-showcase' ),
        'singular_name' => __( 'Portfolio Item', 'portfolio-showcase' ),
        'add_new_item'  => __( 'Add New Project', 'portfolio-showcase' ),
        'edit_item'     => __( 'Edit Project', 'portfolio-showcase' ),
        'menu_name'     => __( 'Portfolio', 'portfolio-showcase' ),
    );

    register_post_type( 'portfolio', array(
        'labels'       => $labels,
        'public'       => true,
        'has_archive'  => true,
        'menu_icon'    => 'dashicons-portfolio',
        'menu_position'=> 20,
        'rewrite'      => array( 'slug' => 'portfolio' ),
        'supports'     => array( 'title', 'editor', 'thumbnail', 'excerpt' ),
        'show_in_rest' => true, // enables the block editor + REST API
    ) );
}
add_action( 'init', 'portfolio_showcase_register_cpt' );

/**
 * Register the hierarchical "portfolio_category" taxonomy.
 */
function portfolio_showcase_register_taxonomy() {
    register_taxonomy( 'portfolio_category', array( 'portfolio' ), array(
        'labels'            => array(
            'name'          => __( 'Portfolio Categories', 'portfolio-showcase' ),
            'singular_name' => __( 'Portfolio Category', 'portfolio-showcase' ),
        ),
        'hierarchical'      => true,   // behaves like categories, not tags
        'show_admin_column' => true,
        'show_in_rest'      => true,
        'rewrite'           => array( 'slug' => 'portfolio-category' ),
    ) );
}
add_action( 'init', 'portfolio_showcase_register_taxonomy' );

function portfolio_showcase_activate() {
    portfolio_showcase_register_cpt();
    portfolio_showcase_register_taxonomy();
    flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'portfolio_showcase_activate' );

Milestone 2 — Meta Boxes, Done Safely

A portfolio item needs more than a title and body: the client name, the completion date, and a live project URL. That extra data lives in post meta, edited through a meta box. This milestone is where most beginner plugins go wrong on security, so we'll do it carefully.

Every meta box has a round trip, and each leg needs a guard:

Register and render the box

function portfolio_showcase_add_meta_boxes() {
    add_meta_box(
        'portfolio_details',
        __( 'Project Details', 'portfolio-showcase' ),
        'portfolio_showcase_render_details',
        'portfolio',
        'side',
        'high'
    );
}
add_action( 'add_meta_boxes', 'portfolio_showcase_add_meta_boxes' );

function portfolio_showcase_render_details( $post ) {
    // Nonce ties this form to this request — proves the save is intentional.
    wp_nonce_field( 'portfolio_details_save', 'portfolio_details_nonce' );

    $client = get_post_meta( $post->ID, '_portfolio_client', true );
    $date   = get_post_meta( $post->ID, '_portfolio_date', true );
    $url    = get_post_meta( $post->ID, '_portfolio_url', true );
    ?>
    <p>
        <label for="portfolio_client"><?php esc_html_e( 'Client', 'portfolio-showcase' ); ?></label>
        <input type="text" id="portfolio_client" name="portfolio_client"
               value="<?php echo esc_attr( $client ); ?>" class="widefat">
    </p>
    <p>
        <label for="portfolio_date"><?php esc_html_e( 'Completed', 'portfolio-showcase' ); ?></label>
        <input type="date" id="portfolio_date" name="portfolio_date"
               value="<?php echo esc_attr( $date ); ?>" class="widefat">
    </p>
    <p>
        <label for="portfolio_url"><?php esc_html_e( 'Project URL', 'portfolio-showcase' ); ?></label>
        <input type="url" id="portfolio_url" name="portfolio_url"
               value="<?php echo esc_url( $url ); ?>" class="widefat">
    </p>
    <?php
}

Save it — with all four guards

Note the wp_unslash() before sanitizing: WordPress adds slashes to $_POST, so you strip them first, then sanitize with a function matched to the data type.

function portfolio_showcase_save_details( $post_id ) {
    // 1. Verify the nonce.
    if ( ! isset( $_POST['portfolio_details_nonce'] )
        || ! wp_verify_nonce(
            sanitize_key( $_POST['portfolio_details_nonce'] ),
            'portfolio_details_save'
        ) ) {
        return;
    }
    // 2. Ignore autosaves.
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
        return;
    }
    // 3. Check the current user is allowed to edit this post.
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return;
    }
    // 4. Sanitize each field to match its type, then store.
    if ( isset( $_POST['portfolio_client'] ) ) {
        update_post_meta( $post_id, '_portfolio_client',
            sanitize_text_field( wp_unslash( $_POST['portfolio_client'] ) ) );
    }
    if ( isset( $_POST['portfolio_date'] ) ) {
        update_post_meta( $post_id, '_portfolio_date',
            sanitize_text_field( wp_unslash( $_POST['portfolio_date'] ) ) );
    }
    if ( isset( $_POST['portfolio_url'] ) ) {
        update_post_meta( $post_id, '_portfolio_url',
            esc_url_raw( wp_unslash( $_POST['portfolio_url'] ) ) );
    }
}
add_action( 'save_post_portfolio', 'portfolio_showcase_save_details' );

Expose a helper for the theme

The theme should never call get_post_meta with your private key names directly — that couples it to your storage details. Give it a clean function instead:

/**
 * Theme-facing helper: fetch a portfolio field with escaping already handled.
 */
function portfolio_showcase_field( $key, $post_id = null ) {
    $post_id = $post_id ?: get_the_ID();
    $value   = get_post_meta( $post_id, '_portfolio_' . $key, true );
    return 'url' === $key ? esc_url( $value ) : esc_html( $value );
}

Milestone 3 — The Theme & Integration

Now the presentation layer. Create a minimal theme at wp-content/themes/portfolio-showcase-theme/. Every theme needs at least a style.css with a header block and an index.php; we add portfolio-specific templates on top.

style.css header + functions.php

/*
Theme Name: Portfolio Showcase Theme
Author: Your Name
Version: 1.0.0
Requires PHP: 8.2
*/

<?php
// functions.php
function portfolio_theme_setup() {
    add_theme_support( 'title-tag' );
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'html5', array( 'gallery', 'caption', 'style', 'script' ) );
    add_image_size( 'portfolio-thumb', 600, 450, true ); // hard crop
}
add_action( 'after_setup_theme', 'portfolio_theme_setup' );

function portfolio_theme_assets() {
    wp_enqueue_style(
        'portfolio-theme',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get( 'Version' )
    );
}
add_action( 'wp_enqueue_scripts', 'portfolio_theme_assets' );

archive-portfolio.php — the grid, with graceful fallback

This is the integration point. The theme checks whether the plugin's helpers exist before calling them, so if the plugin is deactivated the theme degrades instead of fataling.

<?php get_header(); ?>

<main id="primary" class="portfolio-archive">
    <h1><?php post_type_archive_title(); ?></h1>

    <div class="portfolio-grid">
    <?php while ( have_posts() ) : the_post(); ?>
        <article <?php post_class( 'portfolio-card' ); ?>>
            <a href="<?php the_permalink(); ?>">
                <?php if ( has_post_thumbnail() ) {
                    the_post_thumbnail( 'portfolio-thumb' );
                } ?>
                <h2><?php the_title(); ?></h2>
                <?php
                // Feature-detect the plugin before using its helper.
                if ( function_exists( 'portfolio_showcase_field' ) ) {
                    $client = portfolio_showcase_field( 'client' );
                    if ( $client ) {
                        echo '<p class="client">' . $client . '</p>'; // already escaped
                    }
                }
                ?>
            </a>
        </article>
    <?php endwhile; ?>
    </div>
</main>

<?php get_footer(); ?>

A responsive grid with pure CSS

No JavaScript library needed for a clean, responsive grid — modern CSS handles it in a few lines:

.portfolio-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
    gap: 1.5rem;
}
.portfolio-card img {
    width: 100%;
    height: auto;
    display: block;
    border-radius: 8px;
}

The [portfolio] shortcode (plugin side)

Back in the plugin, add a shortcode so users can drop a portfolio grid into any page. Buffer the output and always call wp_reset_postdata() after a custom WP_Query:

function portfolio_showcase_shortcode( $atts ) {
    $atts = shortcode_atts(
        array( 'count' => 6, 'category' => '' ),
        $atts,
        'portfolio'
    );

    $args = array(
        'post_type'      => 'portfolio',
        'posts_per_page' => absint( $atts['count'] ),
    );
    if ( $atts['category'] ) {
        $args['tax_query'] = array( array(
            'taxonomy' => 'portfolio_category',
            'field'    => 'slug',
            'terms'    => array_map( 'sanitize_title', explode( ',', $atts['category'] ) ),
        ) );
    }

    $query = new WP_Query( $args );
    ob_start();

    if ( $query->have_posts() ) {
        echo '<div class="portfolio-grid">';
        while ( $query->have_posts() ) {
            $query->the_post();
            printf(
                '<a class="portfolio-card" href="%s">%s<h3>%s</h3></a>',
                esc_url( get_permalink() ),
                get_the_post_thumbnail( null, 'portfolio-thumb' ),
                esc_html( get_the_title() )
            );
        }
        echo '</div>';
    } else {
        echo '<p>' . esc_html__( 'No projects yet.', 'portfolio-showcase' ) . '</p>';
    }

    wp_reset_postdata(); // restore the main query's global $post
    return ob_get_clean();
}
add_shortcode( 'portfolio', 'portfolio_showcase_shortcode' );

Build Checklist

Work top to bottom. Tick each box only when you've verified it in the browser, not just written the code.

What Good Looks Like

Anyone can make it "work." This rubric separates a passable submission from a professional one — it's the same lens a code reviewer or a WordPress.org plugin reviewer would use.

Summary & Quiz

📚 Further Reading

• WordPress Plugin Developer Handbook
• WordPress Theme Developer Handbook
• WordPress Security APIs (nonces, sanitizing, escaping)
• Reference: register_post_type()

🚀 What's Next?

You've now shipped a complete PHP/WordPress build end to end. Next we shift stacks and mindsets toward component-based frontends — starting with how to compose small, reusable UI pieces into larger interfaces.