Forem: Drazen Bebic

Image Optimization with Next.js and Sanity.io

Drazen Bebic — Wed, 14 Jan 2026 11:00:00 +0000

I was putting the finishing touches on my blog, deployed it to Vercel, and ran straight to Lighthouse to reap the fruits of my hard work. I didn't actually reap the fruits I expected, the performance score was below 80. Why? Because of unoptimized images.

Picking Sanity.io for the backend of my headless blog was a good call. It was easy to set up and get the page running. Initially I just fetched the URL's from Sanity and put them in the next/image component. Done. Except that it didn't work so well and the images were quite often way too large for the container they were shown in.

I sat down and figured it out. Here's the complete workflow I use for optimizing my images in a Next.js frontend which utilizes a Sanity.io backend.

Introduction

This guide will create 4 components which we will use across the application. Here's a run-down of them.

New Image Component

We will create a new SanityImage React component. This component wraps around the next/image component and will be your new go-to component for your images coming from Sanity.

Custom Image Loader

We'll also create a sanityLoader image loader for the next/image component. This will be used in the SanityImage component.

Utility Functions

The urlFor utility function which will be used by the sanityLoader to adjust the image before handing it over to the next/image component.

The urlForImage component used across your application to convert Sanity Image objects to URLs for the SanityImage React component.

Prerequisites

This guide will not show you how to set up Sanity.io with Next.js. I will assume that the initial setup is done. You will need to update your next config, check your Sanity schema for images, and update your GROQ queries.

Configuring Next.js

We will also need to configure the next config file a bit. We need to make 3 changes:

Prefer the avif format over webp because of its superior compression.
Support lower image quality to save bandwidth (75 is default).
Add the Sanity remote patterns so the images can be shown.

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    // Prioritize AVIF, then WebP. Browsers that support AVIF will get it.
    formats: ['image/avif', 'image/webp'],
    // Allow for lower quality images to save bandwidth (default is 75)
    qualities: [60, 75],
    // Since we're using Sanity, remember to add the hostname
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.sanity.io',
      },
    ],
  },
};

export default nextConfig;

Defining the Sanity Schema

The next thing we need to do is to define a proper image schema inside Sanity, so that we get back all the fields we need. You probably have something similar set up, but make sure you have everything covered.

import { defineField } from 'sanity'

export default {
  // ... rest of the schema
  fields: [
    defineField({
      name: 'coverImage',
      title: 'Cover Image',
      type: 'image',
      description: 'This image will be used for the blog post cover and SEO cards.',
      options: {
        hotspot: true, 
        metadata: ['lqip', 'palette'], 
      },
      fields: [
        defineField({
          name: 'alt',
          type: 'string',
          title: 'Alternative Text',
          description: 'Important for SEO and accessibility.',
          validation: (rule) => rule.required().warning('Please provide alt text.'),
        }),
      ],
    }),
  ]
}

Updating the GROQ Query

The last thing we need to prepare is a reusable GROQ snippet for images, so that you don't have to copy-paste the same block multiple times in your GROQ queries.

// A reusable GROQ snippet for images
const imageFields = groq`
  asset->{
    _id,
    url,
    metadata {
      lqip, // The base64 placeholder string
      dimensions {
        width,
        height,
        aspectRatio
      }
    }
  },
  alt,
  hotspot,
  crop
`;

// Using it in your main query
export const POST_QUERY = groq`
  *[_type == "post" && slug.current == $slug][0] {
    _id,
    title,
    // Apply the projection to your image field
    coverImage {
      ${imageFields}
    },
    // ... rest of your fields
  }
`;

Step 1: The Builder Utilities

Now that we're prepared, let's start by creating the utility functions I mentioned earlier. Create a sanity/lib/image.ts file in the root directory of your Next.js application and copy-paste this code into it:

import { createImageUrlBuilder, SanityImageSource } from '@sanity/image-url';
import type { Image } from 'sanity';

import { dataset, projectId } from '../env'; // Your env configuration

const imageBuilder = createImageUrlBuilder({
  projectId: projectId || '',
  dataset: dataset || '',
});

// 1. Returns the builder. Used by our sanityLoader (Step 2)
export const urlFor = (source: SanityImageSource) =>
  imageBuilder.image(source);

// 2. Returns a URL string. Also used for Metadata/OG Images where we can't use next/image
export const urlForImage = (image: Image, width?: number) => {
  const builder = urlFor(image);

  if (width) {
    return builder.width(width).url();
  }

  return builder.url();
};

Step 2: The Sanity Loader

Next.js already has a great Image Optimization API, but our images are hosted on Sanity's CDN and we don't want Next.js to re-process them. Sanity's own CDN is pretty great too, it can crop, resize and convert images on the fly.

This loader will basically be a bridge between Sanity and Next.js. Basically it's telling Next.js: "When you need a 400px wide version of this image, this is how you ask Sanity for it."

Create a file called sanityLoader.ts. By using our urlFor utility, we're making sure that any hotspots or crops defined in the Studio are automatically respected.

'use client';

import { ImageLoaderProps } from 'next/image';
import { urlFor } from '@/sanity/lib/image';

export default function sanityLoader({ src, width, quality }: ImageLoaderProps) {
  return urlFor(src)
    .width(width)
    .quality(quality || 75)
    .auto('format') // Serves AVIF or WebP based on browser support
    .fit('max')
    .url();
}

Step 3: The Wrapper Component

Repeating code is bad. Writing loader={sanityLoader} everywhere is just a pain. Instead, we'll create a reusable <SanityImage /> wrapper component.

This React component will handle the very basic boilerplate. It will assign the loader and pass all other props directly to the next/image component with the exception of the loader prop.

'use client';

import { FC } from 'react';
import Image, { ImageProps } from 'next/image';

import sanityLoader from '@/utils/sanity-loader';

export type SanityImageProps = Omit<ImageProps, 'loader'>;

export const SanityImage: FC<SanityImageProps> = props => {
  // Already included in ImageProps
  // eslint-disable-next-line jsx-a11y/alt-text
  return <Image quality={60} {...props} loader={sanityLoader} />;
};

I also had to disable an ESLint rule to keep it happy, but that's all there is to it.

Step 4: The sizes Property

The final piece of the puzzle. This is the part I understood the least so I had to look it up a bit, but essentially it boils down to displaying different image sizes for different screen sizes.

Let's imagine you're displaying a 3-column grid on desktop. The image is only 300px wide, if you don't define sizes the browser will think that it needs an image which fits the whole screen. This way you'll possibly download a 4K and display it in a 300px container. This will absolutely annihilate your LCP score.

You need to tell the browser exactly how much space the image occupies at different breakpoints. Here's a real-world example:

The Layout:

Mobile (< 768px): 1 column (Image is wide, ~90vw)
Tablet (< 1200px): 2 columns (Image is ~45vw)
Desktop (>= 1200px): 3 columns (Image is ~30vw)

The Code:

import { urlForImage } from '@/sanity/lib/image';

const coverImageUrl = urlForImage(post.coverImage);

<SanityImage
  src={coverImageUrl}
  className="object-cover"
  // The crucial part for performance:
  sizes="(max-width: 768px) 90vw, (max-width: 1200px) 45vw, 30vw"
/>

Translation:

Is the screen smaller than 768px? → Download the 90vw variant.
Is it smaller than 1200px? → Download the 45vw variant.
Larger? → Download the 30vw variant.

By implementing this, I saw my network payload for images drop by over 60%.

Conclusion

While it seems like it at first, optimizing images in a Headless CMS environment doesn't have to be a black box. Enable AVIF in Next.js, implement a loader that makes sense for your CMS, and you can achieve near-instant load times.

Next.js and Sanity are a great couple. They give you the tools to score that 100 on Lighthouse, you just have to wire them together and you're golden.

How to Add Settings Pages to WordPress Plugins: A Developer's Guide

Drazen Bebic — Sun, 04 Jan 2026 00:16:01 +0000

In my previous blog post we created a "Read Time" plugin. The idea is simple: Show how long it takes to read the article. There is one major issue with it though: The reading time is calculated using 200 words per minute, and this value is hardcoded.

Let's say you want to change this, because you know your users read faster or slower. Maybe you even have a per-user setting for this. It'll be impossible to do that with the current state of the plugin. Hardcoding variables like these is bad practice. So let's fix it by adding a setting.

This is the second post in our "Mastering WordPress Plugins" series. In this part we will make the words per minute dynamic by adding a setting with the WordPress Setting API , and retrieving it with the WordPress Options API.

The Goal

We're going to:

Add a "Settings" link for our plugin in the WordPress admin menu.
Create a simple form where the administrators can enter their preferred "Words Per Minute" value.
Save that value securely using the Settings API.
Update our calculation logic to use this new value.

Prerequisites

You'll need the code from part 1. If you don't have it already, here's the link to the GitHub Gist.

Step 1: Registering the Menu Item

Let's start by creating the setting. The administrators will need to be able to access this, so we'll add it as a sub-menu item under the "Settings" menu item on the WordPress Dashboard Sidebar.

Open your simple-read-time.php file and copy-paste this code at the end of the file:

/**
 * Registers the settings page.
 */
function srt_register_settings_page() {
    add_options_page(
        'Simple Read Time Settings', // Page Title
        'Read Time', // Menu Title
        'manage_options', // Capability required (Admins only)
        'simple-read-time', // Menu Slug
        'srt_render_settings_page' // Callback function to render HTML
    );
}
add_action( 'admin_menu', 'srt_register_settings_page' );

By adding this code we're letting WordPress know that there is a new sub-menu item under "Settings". For this purpose we're hooking into the admin_menu action and calling add_options_page() inside of it. The srt_render_settings_page callback function will render the form and display the content.

Step 2: Registering the Setting

Let's first tell WordPress about this new setting so that it actually gets stored inside the database before we create the form for it. We will now hook into admin_init and call register_setting() function to achieve this.

Add this code to your file:

/**
 * Registers the setting to be saved in the database.
 */
function srt_register_settings() {
    register_setting(
        'srt_options_group', // Option Group Name
        'srt_reading_speed', // Option Name (Database Key)
        array(
            'type' => 'integer',
            'default' => 200,
            'sanitize_callback' => 'absint', // Security: Force it to be a positive integer
        )
    );
}
add_action( 'admin_init', 'srt_register_settings' );

You probably noticed the sanitize_callback and that its value is absint. This is a WordPress function which returns the absolute value of an integer (i.e. -50 -> 200).

This is a security measure. We're making sure that, even if a user types in an incompatible value such as -50 or even "hello", WordPress converts it into a positive integer (or zero) before saving it.

We do this because you can never trust user input.

Step 3: Rendering the Settings Page

Now that we have everything else set up, let's create the actual HTML form. WordPress provides some helper functions which do make life a bit easier.

Once again, copy-paste this code to the bottom of your file:

/**
 * Renders the HTML for the settings page.
 */
function srt_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>Simple Read Time Settings</h1>
        <form method="post" action="options.php">
            <?php
            // Output security fields for the registered setting "srt_options_group"
            settings_fields( 'srt_options_group' );

            // Output setting sections and their fields
            do_settings_sections( 'srt_options_group' );
            ?>

            <table class="form-table">
                <tr>
                    <th scope="row">Words Per Minute</th>
                    <td>
                        <input type="number" name="srt_reading_speed" value="<?php echo esc_attr( get_option( 'srt_reading_speed', 200 ) ); ?>" />
                        <p class="description">Average reading speed (Default: 200)</p>
                    </td>
                </tr>
            </table>

            <?php submit_button(); ?>
        </form>
    </div>
    <?php
}

There's quite a bit going on here but don't worry, we'll break it down:

settings_fields: This function will output hidden inputs like the Nonce (security token).
get_option: This is part of the WordPress Options API. It's used to fetch an option's value from the database. The second parameter (200) is the default value which is used if the value doesn't exist yet.

What is a Nonce you ask? It stands for "Number used ONCE" and it's used to prevent malicious attacks like Cross-Site Request Forgery (CSRF). It basically makes sure that the request came from your website, and not somewhere else.

Step 4: Connecting the Logic

So far so good! We can now save the value into the database. It's time to update our logic from Part 1 and utilize the stored database value for the words per minute.

Find your srt_add_reading_time function and modify the $reading_speed line:

function srt_add_reading_time( $content ) {
    // ... existing check code ...

    $word_count = str_word_count( strip_tags( $content ) );

    // OLD: $reading_speed = 200;

    // NEW: Get the dynamic value from the DB
    $reading_speed = get_option( 'srt_reading_speed', 200 );

    // Safety check: Prevent division by zero if someone saves "0"
    if ( $reading_speed < 1 ) {
        $reading_speed = 200;
    }

    $reading_time = ceil( $word_count / $reading_speed );

    // ... existing HTML wrapper code ...
}

Refresh your page and you should be seeing something like this:

Conclusion

You're done! Your hardcoded value is now gone and replaced with a proper solution.

You have learned how to:

Register a menu page (add_options_page).
Register a database setting (register_setting).
Sanitize input (absint).
Retrieve dynamic values (get_option).

So what's next for your plugin? Well, sky's the limit, but the next part of this series will focus on WordPress Security through Nonces which I mentioned earlier.

In this guide we are automatically protected by using the settings_fields() function. But what if you are building a custom form? You'll need to handle this part yourself.

I have also created a GitHub Gist of the updated plugin.

How to Create Your First WordPress Plugin: A Developer's Guide

Drazen Bebic — Sun, 28 Dec 2025 21:09:22 +0000

Most WordPress developers start out by adding functionality in the form of code snippets to the functions.php file. While this is a completely valid approach for quick fixes and small additions, it is not scalable architecture. If you change your theme you lose all of your functionality.

The solution is to build a WordPress Plugin.

Plugins are the gold standard for extending WordPress functionality. They are good because they decouple your custom functionality from the visual presentation of your website. This guide will cover the core concepts of WordPress plugin development (including hooks and filters) by building a simple plugin from scratch.

What Actually is a WordPress Plugin?

At its very core, a WordPress plugin is just a simple PHP file located in the wp-content/plugins/ directory and follows a specific header format.

WordPress scans this directory when it loads and looks for these kind of files. When it finds files with valid metadata it registers them so that you can activate them through the admin dashboard. Once you activate them, the code found inside the plugin file(s) runs on every page load. This is your entry gateway to injecting logic, modifying database queries, or rendering custom HTML.

Prerequisites

You will need a local WordPress development environment. Luckily there are many great options to chose from. I recommend:

LocalWP (easiest to set up)
DDEV or Lando (if you prefer Docker-based workflows)

Since WordPress is written in PHP you will also need some basic PHP knowledge. You absolutely don't have to be a wizard, but you should understand functions, arrays, and basic logic flow.

Step 1: The Folder Structure

Let's get started! First thing that you need to do is to navigate to your wp-content/plugins/ directory and create a new folder named simple-read-time. Inside this folder, create a PHP file called simple-read-time.php.

It is best practice and convention to name your main PHP file the same as your folder to avoid confusion.

Step 2: The Plugin Header

I mentioned that WordPress scans for specific metadata inside plugin files. This metadata is in the form of a comment block which sits at the top of your plugin PHP file. It looks something like this:

<?php
/**
 * Plugin Name: Simple Read Time
 * Plugin URI: https://www.bebic.dev
 * Description: A lightweight plugin that calculates and displays the estimated reading time for blog posts.
 * Version: 1.0.0
 * Author: Drazen Bebic
 * Author URI: https://www.bebic.dev
 * License: GPL2
 */

// Prevent direct access to the file
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

After doing this you should be able to see your plugin on the Plugins page:

Developer Tip: Always include the defined('ABSPATH') check. This prevents malicious actors from executing your PHP file directly, bypassing the WordPress loading process.

Step 3: Understanding Hooks (Actions vs. Filters)

This is the part where it gets a bit tricky, but it's important to learn the difference because it is the very heart of WordPress development: hooks.

There's two types of hooks in WordPress:

Actions (add_action): Events where you want to do something at a specific point (e.g., "When a post is saved, send an email"). Actions do not return data.
Filters (add_filter): Events where you want to modify data before it is rendered or saved (e.g., "Take the post content, add a disclaimer to the bottom, and return it"). Filters must return data.

Our plugin is going to calculate the reading time of blog posts and prepend it to the their content. This process will modify the output, so we will need to use a filter.

Step 4: Building the Logic

Now that we know what to do, let's go ahead and do it. We will hook into the the_content. This hook controls the body text of any post.

Add this code to your plugin file:

/**
 * Calculates reading time and prepends it to the content.
 *
 * @param string $content The original post content.
 * @return string The modified content.
 */
function srt_add_reading_time( $content ) {
    // Only run on single posts, not on the homepage or archives
    if ( ! is_single() || ! is_main_query() ) {
        return $content;
    }

    // 1. Get the word count (strip HTML tags first)
    $word_count = str_word_count( strip_tags( $content ) );

    // 2. Average reading speed (roughly 200 words per minute)
    $reading_speed = 200;

    // 3. Calculate time
    $reading_time = ceil( $word_count / $reading_speed );

    // 4. Create the HTML wrapper
    $reading_time_html = sprintf(
        '<p class="srt-read-time"><small>%s min(s) read.</small></p>',
        $reading_time
    );

    // 5. Prepend to content and return
    return $reading_time_html . $content;
}

// Hook our function to the 'the_content' filter
add_filter( 'the_content', 'srt_add_reading_time' );

What is happening here?

The Check : is_single() ensures our filter only runs on single blog posts so that we don't accidentally clutter the homepage or blog feed.
The Logic : We strip HTML tags from the body to get a pure word count, then divide this word count by 200 (average reading speed).
The Return : We append our newly created HTML to the original $content so nothing gets lost. If we forgot to return $content at the end of the hook callback, the entire blog post would be blank. This would be bad.

Step 5: Adding Settings (Optional but Recommended)

Hardcoding the reading speed (200) is fine for a v1, but in a real-world scenario, you might want to make that customizable.

To do that, you would typically use the Settings API or the Options API to store a value in the wp_options table.

// Example of retrieving a saved option (defaults to 200 if not found)
$reading_speed = get_option( 'srt_reading_speed', 200 );

For the sake of simplicity and keeping this guide digestible we will not cover the topic of creating a settings page. I will create a second part about this specific topic in my next blog post, so stay tuned!

Conclusion

Congratulations! You have built your very own WordPress plugin from scratch. Your end result will look a bit like this:

You can now move from "hacking the functions.php" to writing modular, reusable software. You know how to set up the plugin files and folders, create some hooks and inject logic into the WordPress rendering pipeline.

I have also created the full plugin avilable in the form of a GitHub gist right here.

Your next step? Maybe refactor your functions.php into one (or more?) plugins. You could also try to expand this plugin. Or perhaps stay tuned for the next part where I will explain how to utilize the Settings API and Options API of WordPress.

What is JSON-LD? A Developer's Guide to Structured Data

Drazen Bebic — Mon, 22 Dec 2025 21:57:59 +0000

Today's search engines can do a lot of things, but they can't do everything. When a crawler like Googlebot visits your site, it parses the HTML to render the page, but scraping the DOM to understand context is inefficient and prone to errors.

That is where JSON-LD comes in. It is a standardized way to tell search engines about the content of your website, completely detached from how this content appears to the user.

If you are serious about SEO and getting noticed by SERPs (Search Engine Results Pages), you will come across JSON-LD and you will most definitely need to understand it and implement it.

What is JSON-LD?

JSON-LD stands for JavaScript Object Notation for Linked Data. Quite a lot of words packed into that, but don't worry. What you need to know is that it's a very lightweight Linked Data format which allows you to embed structured data using a simple <script> tag.

The main benefit of JSON-LD is that you can completely decouple the data layer from the presentation layer. Website visitors see one thing, the crawlers see something else.

This magical JSON-LD block usually lives in the <head> of your document (but it can also be found in the body) inside a specific script block:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Drazen",
  "jobTitle": "Senior Fullstack Developer",
  "url": "https://www.bebic.dev"
}
</script>

When Googlebot sees this page it can automatically infer who "Drazen" is, without needing to guess it by parsing an <h1> tag. The JSON-LD structured data explicitly tells it that there is a Person with this name. Cool stuff.

Why JSON-LD is the Winner for SEO

This one is easy to answer: Google. There are several ways to implement structured data (Microdata, RDFa), but JSON-LD is king because it's recommended by Google.

The main reason why you want to implement JSON-LD is Rich Results. It's important to know that structured data is not a direct ranking factor, but it allows Google to display visually enhanced results inside searches.

These enhancements are enough to give you an edge and drastically improve Click-Through Rates (CTR). Here's an example of a product information Rich Result:

Here you can see the price and stock status of the product directly in your Google Search (Thanks, JSON-LD!). This is very low-hanging fruit for developers: A small JSON object can significantly increase the traffic your website receives.

Core Syntax and Structure

The syntax relies on a vocabulary defined by Schema.org. Here are the key components you will encounter:

@context: This defines the vocabulary being used. It is almost always "https://schema.org".
@type: This defines the entity you are describing (e.g., Article, Product, Organization).
Properties: Key-value pairs specific to that type.

Nesting Objects

JSON-LD really shines once you start linking data. In this example you're not just describing a product, no no; you're describing a product that has an offer, which is then sold by an Organization!

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Arctic Road Cargo M",
  "description": "With its signature cargo pockets, [...]",
  "offers": {
    "@type": "Offer",
    "price": "149.95",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/InStock"
  }
}

Moving from Theory to Practice

So now that you understand the meaning and syntax of JSON-LD the next step is to programmatically generate this JSON-LD stuff using your data.

In a modern stack, you won't write these JSON-LD objects yourself. You will write a function which will generate it for you. If you are using a frontend framework like Next.js, you will likely generate and inject JSON-LD dynamically using data fetched from your backend.

In a previous blog post I have explained how JSON-LD can be implemented with React and Next.js. Check out the written guide here: Enhance Your SEO with JSON-LD: A Practical Guide.

Validation and Debugging

Once you've written the JSON-LD object you're not done. Always test your structure before deploying changes. An invalid JSON-LD object can and will invalidate the entire block, causing your Rich Results to go poof.

Use these two tools:

Rich Results Test (Google): Tells you if your page qualifies for rich snippets (Stars, FAQs, etc.).
Schema Markup Validator (Schema.org): Validates the syntax and logic of your JSON-LD, even if it doesn't trigger a specific Google feature.

Automated Testing

Manually testing is okay, but it doesn't scale. If you want to get serious about SEO, you need to treat structured data just like any other critical part of your code and test it automatically.

Google's Lighthouse has a specific audit called "Structured data is valid". You can run this programmatically in your CI pipeline using the Lighthouse CI CLI.

If you want to verify the very structure of the JSON-LD your function injects into the DOM, you can write a simple E2E test with tools like Cypress or Microsoft Playwright.

Here is a Playwright example that scrapes the script tag and parses it to ensure it is valid JSON and contains expected data:

test('Homepage has valid JSON-LD', async ({ page }) => {
  await page.goto('https://localhost:3000');

  // Select the script tag
  const jsonLdScript = await page.$('script[type="application/ld+json"]');
  const content = await jsonLdScript.textContent();

  // Parse it to ensure valid JSON
  const data = JSON.parse(content);

  // Assert critical properties exist
  expect(data['@type']).toBe('WebSite');
  expect(data.name).toBe('Bebic.dev');
});

Conclusion

JSON-LD is the mediator between your application's data and the search engines. It's the invisible bridge between your website's content and Google and friends. Standardized and decoupled, a developer's dream!

It allows us developers to contribute to the SEO success of a project in a way that is sensible to us. I recommend that you treat JSON-LD as a core part of your data layer and your search performance will thank you for it.

Unleash Your Inner Avenger: A Beginner's Guide to Unix Shells

Drazen Bebic — Tue, 24 Sep 2024 17:38:03 +0000

Let's talk about shells. If you're new to Unix or Linux systems, you've probably heard the term "shell" tossed around like it's common knowledge. But what exactly is a shell? Why are there so many different ones? And what does Iron Man have to do with this? Let's break it down together. We'll dive into the basics of Unix shells, explore the most common ones, and I'll show you how to customize them to make your workflow smoother—just like Tony Stark fine-tuning his armor.

What Exactly Is a Shell?

Alright, so what's a shell, really? In simple terms, a shell is a command-line interpreter that gives you a way to interact with the Unix operating system. It lets you execute commands, run scripts, and launch applications—all from a text-based interface. Think of it as the middleman between you and the kernel (the core part of the operating system). It's like having your own Jarvis, but instead of voice commands, you're typing away.

Shell vs. Terminal: What's the Difference?

So you've probably heard people use "shell" and "terminal" interchangeably. Well, they're not the same thing:

Shell: The program that processes your commands and gives you the output.
Terminal: The interface or window where you type in those commands and see the results.

Think of the terminal as the Iron Man suit, and the shell as Tony Stark inside controlling everything. Just like how the suit is the physical interface that allows Tony to interact with the world, the terminal is where you interact with the shell. And yes, Tony can control his suits remotely—just like you can SSH into remote machines—but at the core, it's Tony (the shell) making things happen.

Common Unix Shells Explained

Over the years, people have come up with all sorts of different shells, each with its own features and quirks. It's almost like the Marvel Universe introducing new superheroes to keep us on our toes. So, let's dive into some of the most common ones and see what they're all about:

Bourne Shell (`sh`)

Overview: The O.G. Unix shell developed by Stephen Bourne.
Features: Basic scripting capabilities, simple syntax.
Usage: While largely replaced by more advanced shells, sh scripts are still used for compatibility reasons.

Think of sh as the Mark I suit—rudimentary, but it laid the groundwork for everything that came after.

Bourne-Again Shell (`bash`)

Overview: An improved version of sh, developed for the GNU Project.
Features: Command history, tab completion, improved scripting syntax.
Usage: The default shell on many Linux distributions. Great for both interactive use and scripting.

bash is like the Mark III suit—sleeker, more powerful, and packed with new features that make life easier. Comes in hot rod red.

Z Shell (`zsh`)

Overview: Combines features from other shells with unique enhancements.
Features: Advanced tab , shared history among sessions, plugin and theme support (e.g., Oh My Zsh).
Usage: Popular among power users and developers for its customization capabilities.

Imagine zsh as the nano-tech suit from Infinity War—advanced, adaptable, and ready for any situation.

Korn Shell (`ksh`)

Overview: Developed by David Korn at AT&T Bell Labs.
Features: Enhanced scripting, improved performance over sh
Usage: Preferred in some enterprise environments and for advanced scripting.

Think of ksh as the Hulkbuster suit—built for specific tasks and packing extra power when you need it.

Tenex C Shell (`tcsh`)

Overview: An enhanced version of the C Shell (csh).
Features: Filename completion, command-line editing.
Usage: Favored by some due to its C-like syntax, but less common today.

tcsh is like War Machine—a solid performer with its own set of features, but not as widely used as Iron Man's main suits.

Customizing Your Shell

Now, here's one of the best things about Unix shells: you can customize them to suit your workflow. Seriously, you can tweak and tailor them until they fit your needs perfectly. Just like Tony Stark can't stop tinkering with his suits—we're talking Mark 85 here—you can keep refining your shell to make it your ultimate tool.

Understanding Shell Configuration Files

Each shell has its own configuration file where you can set up your customizations. Here's a quick rundown:

~/.bashrc: Configuration file for bash. Loaded in interactive non-login shells.
~/.bash_profile: Loaded by bash in login shells.
~/.zshrc: Configuration file for zsh.
~/.tcshrc or ~/.cshrc: Configuration files for tcsh and csh.
~/.kshrc: Configuration file for ksh.
~/.profile: General startup file for login shells, read by many shells.

Think of these configuration files as your own set of blueprints, like Tony's schematics for his suits. By editing them, you're engineering your own personal Iron Man suit.

Modern Shells and Tools

While traditional shells are pretty powerful, modern shells and tools bring enhanced features that can really level up your endgame:

Fish Shell: User-friendly and feature-rich shell with syntax highlighting and autosuggestions.
- Website: fishshell.com
PowerShell: Originally from Windows, now cross-platform with advanced scripting capabilities.
- Website: github.com/PowerShell/PowerShell
Nu Shell: A modern shell that brings a structured data approach.
- Website: nushell.sh

These modern shells are like Tony's bleeding-edge nano-tech suits—pushing boundaries and offering new capabilities that traditional shells don't.

Conclusion

Mastering Unix shells is like becoming a genius/billionaire/playboy/philanthropist—crafting tools that make you more efficient and powerful. Whether you're sticking with bash, dabbling in zsh, or exploring modern shells like Fish, customizing your environment can seriously amp up your productivity.

So suit up, customize your shell, and take control of your computing experience.

Alright, I'll stop with the Marvel references. I don't want to get sued by the Mouse.

What Did I Do? A Time-Tracking Problem

Drazen Bebic — Wed, 18 Sep 2024 09:00:00 +0000

Like many other developers I work for a software agency. We sell development hours for money. Pretty straightforward. To know how much we have to bill to which one of our customers we use time-tracking software. And let's be honest—keeping track of time can sometimes feel like the hardest part of the job. So, I built a little tool to make this chore a bit easier.

I am lazy

In an ideal world where developers aren't lazy and the beer flows freely I would keep track of the time spent on my tasks as I work on said task. But since we don't live in an ideal world, and I am a lazy developer, I find myself often in the position of toggling the entire week (or longer) on a Friday.

Ever found yourself at the end of the week wondering what you even did? Yeah, me too.

But I am a developer, too

As you can see, this was starting to become a problem because: Who the hell knows what they did 4 days ago, right? Well I found a solution to the problem: wdid

wdid stands for "What did I do?" and is a simple bash script which I added to my .zshrc file. This little script has saved me countless times. It's dead simple—just a function that fetches my Git logs by date. Here's what it looks like:

function wdid() {
  local USERDATE=$1;

  if [ -z "$USERDATE" ]; then
    git log --all --author="$(git config user.name)" --pretty=format:'(%cs) - %s'
    return;
  fi

  if [[ "$USERDATE" == "today" ]]; then
    USERDATE=$(date '+%Y-%m-%d')
  fi

  git log --all --author="$(git config user.name)" --pretty=format:'(%cs) - %s' --after="$USERDATE 00:00" --before="$USERDATE 23:59"

  return;
}

With this script, I can easily print out the Git logs of a specific date for the repository I'm currently in. For example, if today was Friday, the 13th of September 2024, and I needed to know what I did on Monday of that week (the 9th of September), I would simply do this:

wdid 2024-09-09

The output would look something like this:

(2024-09-13) - fix(TICKET-01): add pre-commit hooks
(2024-09-13) - fix(TICKET-05): update dependencies

Nifty, right? Since we use the ticket numbers in our commits it makes this whole thing very easy to follow. You can also do wdid today to get today's Git logs, but I haven't used that yet, to be honest. My memory isn't that bad... yet.

You can hold a job?

I know. Why don't I just keep track of the hours as I work on them, you ask? Well, I try to do that too, but too often, I'm overly focused on the task at hand and can't be bothered with clocking in the hours right away.

Instead of stressing out every Friday trying to remember the details of my week, wdid gives me a clear snapshot of what I’ve done. It’s simple, fast, and takes the guesswork out of time-tracking.

I’m trying to improve on the whole "track your time as you go" thing, and I am making some progress, but wdid still saves my hide at least once a month.

Linking Private GitHub Repositories as Composer Dependencies

Drazen Bebic — Tue, 17 Sep 2024 09:00:00 +0000

When you work with multiple Composer-based repositories, you might find the need to share some PHP code between them. If these were public repositories, this article would be a lot shorter. However, since they're private, you can't just add them to the composer.json and expect it to work. But don't worry—it's not that difficult to set up either.

Creating our Package

Let's get right into it and create the Composer package we want to share across our private repositories.

GitHub Repository

First, let's create a new Repository in GitHub. We'll call this one composer-package. Original, I know. Make sure you set it to private. Clone the repository onto your machine and cd into it.

Composer Initialization

The easiest way to setup a Composer-based PHP project is to run composer init. You can either run that command as is or pass additional parameters to it (feel free to change them):

composer init \
    --name="drazen-bebic/composer-package" \
    --description="Private Composer Package" \
    --author="Drazen Bebic <drazen@example.com>" \
    --type=library \
    --license=MIT \
    --autoload=src/

Then just follow through with the prompts:

Run composer install to get everything installed and the autoloader ready. After that, create a .gitignore and add the vendor directory to it. When you've done all that you should have exactly 5 things in your project:

.gitignore
composer.json
composer.lock
vendor
src

And if you look at your composer.json file, it should look a little like this:

{
    "name": "drazen-bebic/composer-package",
    "description": "Private Composer Package",
    "type": "library",
    "license": "MIT",
    "autoload": {
        "psr-4": {
            "DrazenBebic\\ComposerPackage\\": "src/"
        }
    },
    "authors": [
        {
            "name": "Drazen Bebic",
            "email": "drazen@example.com"
        }
    ],
    "require": {}
}

You surely noticed the autoload key in your composer.json. This part tells the autoloader where, and under which namespace, it can find the Package's source files.

Versioning

Once you're done, commit and push your changes to GitHub. You're not done yet though! For an easy life, you'll want your Composer packages to be versioned. For them to be versioned, they need to have git tags. So let's add the v1.0.0 tag to our latest commit:

git tag v1.0.0

And now let's push the tag to GitHub:

git push origin tag v1.0.0

Now your package is ready to be consumed in its first ever release - v1.0.0. Instead of pushing tags, you could have also required your package using the branch name, but I find this a little bit easier to understand and it's not that much extra work.

If you really want to go all out on versioning, you could add something like the Semantic Release package and generate your versions automatically.

Consuming in a Public Repository

Let's do the easy one first. Let's say the Composer package is publicly available on GitHub and you want to add it to your project.

To do this, just add the following to your composer.json:

{
    "require": {
        ...
        "drazen-bebic/composer-package": "^1.0.0",
        ...
    },
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/drazenbebic/composer-package.git"
        }
    ],
}

After that, all you have to do is run composer update and that's it.

Consuming in a Private Repository

Now the part that you're actually here for. The steps are identical to when you're consuming the package in a public repository, except that there are also a couple of steps on top of that:

Create a GitHub PAT

First we will create a GitHub PAT, aka "Personal Access Token". This access token will be used to authenticate with GitHub and allow us to download the package from the private repository. Let's head over to GitHub and create our token.

We'll select the fine-grained token, give it a name, set the expiration date we want. Don't forget to scope it so that it only has access to the composer-package repository!

And don't forget to set the correct permissions! All we actually need is the Contents permission and we want to set it to "Read-only".

Now just hit the "Generate Token" button and you'll be greeted with the following screen:

Copy the token and store it in some sort of Password Manager or something similar because you'll never see the token again once you close this window. I mean, you can always create a new token, but just store it in a secure place. Trust me.

PS: I know. It's on purpose. By the time you're reading this it's already been deleted.

Local Authentication

Now you basically have everything you need. It's time to connect the last couple of dots. To be able to use this locally, on your machine, you need to register the PATH with Composer like so:

composer config -g github-oauth.github.com <YOUR_PAT>

Replace <YOUR_PAT> with your actual PAT you've generated previously. And that's it! Now you can just run composer install or composer update and Composer will be able to install your package locally.

Workflow Authentication

So you've got this working locally, but what if you have a GitHub Workflow which needs to install this package in a GitHub Runner? No worries, it's just a couple of extra steps.

Add the PAT to the GitHub Repository Secrets. I used the COMPOSER_AUTH key.
In your workflow files, where you're running composer install, pass the following env:

Here's an excerpt from my deployment.yml file:

name: 'Deployment'

on:
  workflow_dispatch:

jobs:
  deploy:
    name: 'Deploy'
    timeout-minutes: 20
    runs-on: ubuntu-latest
    steps:
      - uses: shivammathur/setup-php@v2
        with:
          php-version: 8.3
          tools: composer:v2
      - name: Install dependencies
        run: composer install
        env:
          COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{secrets.COMPOSER_AUTH}}"} }'

Of course there are other steps before and after, but these are the most important since they install PHP, Composer, and the Composer dependencies using our PAT.

Wrapping up

And that's pretty much it! Linking private GitHub repositories as Composer dependencies isn't as tricky as it might seem. With your package set up, a GitHub PAT in hand, and authentication configured both locally and in your workflows, you're all set to share code across your private repositories.

Here's the link to the Composer Package Repository on my GitHub and a virtual avocado 🥑 for your efforts. Happy Coding!

Optimizing and Cleaning Up Your WordPress Database: A DIY Guide

Drazen Bebic — Tue, 10 Sep 2024 09:00:00 +0000

As your WordPress project grows, you may begin to notice performance issues, often caused by a bloated database. While there are many plugins available to help clean up your database, sometimes it's good to know how to do it yourself. This guide will walk you through manually cleaning and optimizing your WordPress database.

Backup first - It's Critical!

Before making any changes to your database, always create a backup. The steps below involve running destructive SQL queries that will permanently delete data, and you don’t want to lose anything important. A backup will ensure that you can recover in case anything goes wrong.

Plugin Alternatives

If you’re not comfortable running SQL queries manually, don’t worry—there are some excellent plugins that can automate the process for you. Here are a few highly recommended options:

These plugins handle a variety of database cleanup tasks efficiently. Even if you go the plugin route, you should still create a backup before running any database cleanup operations, just to be safe.

What Are We Cleaning?

The goal is to remove unnecessary data that accumulates in your database over time—data you no longer need but which can slow down your site. Here's what we'll be targeting:

Transients: Temporary data stored in the database.
Revisions: Old post versions.
Auto-Drafts: Automatically saved drafts that were never published.
Orphaned Post Meta: Metadata for posts that no longer exist.
Spam and Trashed Comments: Unwanted comments cluttering your database.
Orphaned Relationships: Unused term relationships (tags, categories).
Expired Sessions: Old user session data.
Old Plugin Options: Unused options left behind by deactivated or deleted plugins.
Unattached Media: Media files without a parent post (though this won't delete the actual files).

By removing these unnecessary items, you can significantly improve your WordPress database performance.

Remember to backup your database before proceeding. Additionally, we’ll wrap all SQL statements in a transaction, allowing you to roll back changes if something doesn’t go as planned.

Enhancing Database Performance

Aside from cleaning your database, you can also improve performance by optimizing frequently used tables. This reduces fragmentation and keeps your database running smoothly.

Ready to Clean?

If you’re confident and ready, copy and paste the following SQL queries into your WordPress server’s SQL console. Feel free to skip any queries by commenting them out or removing them.

If your WordPress database uses a custom table prefix, replace the default wp_ prefix in the queries with your own.

Optimization Query

This query optimizes some of the most commonly used WordPress tables:

-- Optimize commonly used WordPress tables to reduce fragmentation
OPTIMIZE TABLE wp_posts, wp_postmeta, wp_options, wp_usermeta, wp_comments;

Cleanup Query

Here’s the cleanup portion, wrapped in a transaction so that you can roll it back if needed:

-- Start the transaction
START TRANSACTION;

-- Remove transients (temporary data)
DELETE FROM wp_options WHERE option_name LIKE '_transient_%' OR option_name LIKE '_site_transient_%';

-- Remove post revisions
DELETE FROM wp_posts WHERE post_type = 'revision';

-- Remove auto-drafts
DELETE FROM wp_posts WHERE post_status = 'auto-draft';

-- Remove orphaned post meta (meta data for non-existent posts)
DELETE pm FROM wp_postmeta pm LEFT JOIN wp_posts wp ON wp.ID = pm.post_id WHERE wp.ID IS NULL;

-- Remove orphaned comment meta
DELETE FROM wp_commentmeta WHERE comment_id NOT IN (SELECT comment_id FROM wp_comments);

-- Remove spam and trashed comments
DELETE FROM wp_comments WHERE comment_approved IN('spam', 'trash');

-- Remove orphaned term relationships (tags, categories linked to non-existent posts)
DELETE tr FROM wp_term_relationships tr LEFT JOIN wp_posts wp ON wp.ID = tr.object_id WHERE wp.ID IS NULL;

-- Remove expired user sessions
DELETE FROM wp_usermeta WHERE meta_key = '_wp_session_expires' AND meta_value < UNIX_TIMESTAMP();

-- Remove old, non-autoloading plugin options
DELETE FROM wp_options WHERE autoload = 'no';

-- Identify unattached media files (this won't delete the files, just shows them)
SELECT * FROM wp_posts WHERE post_type = 'attachment' AND post_parent = 0;

-- Commit the transaction (to apply changes)
COMMIT;

Rollback If Something Goes Wrong

If you encounter any issues or if something doesn’t look right, you can cancel the transaction and revert the changes:

-- Rollback the transaction if you don't want to commit the changes
ROLLBACK;

Conclusion

Regularly cleaning and optimizing your WordPress database is essential for maintaining good performance, especially as your site grows. Whether you prefer to do it manually or use a plugin, the important thing is to ensure that your database doesn’t become a bottleneck.

By following this guide, you can clean up and optimize your database safely and efficiently, keeping your site running smoothly. And remember: always, always back up before making changes!

Enhance Your SEO with JSON-LD: A Practical Guide

Drazen Bebic — Tue, 03 Sep 2024 07:00:00 +0000

JSON-LD is a critical piece of the SEO puzzle, especially when you want to enrich your search results with valuable information such as the opening hours of your hair salon, the menu items of your restaurant, or the venue details of your event. In short: you need this to stand out in search results.

What is JSON-LD?

JSON-LD stands for JavaScript Object Notation for Linked Data. It’s a lightweight and easy-to-use format to structure your website’s data so that search engines like Google can better understand and enhance your content with rich snippets, knowledge panels, and other search features.

While there are other types of structured data formats, such as Microdata and RDFa, it’s important to note that Google recommends using JSON-LD for implementing structured data.

Getting Started with JSON-LD

Setting up JSON-LD on your website might seem daunting, but rest assured—it’s simpler than it sounds. While anything related to SEO can appear complex, JSON-LD is just a matter of embedding some structured data in your HTML.

The JSON-LD data should be placed inside a <script/> tag with the type attribute set to application/ld+json. Here’s a basic example:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "John Doe",
  "jobTitle": "Software Engineer",
  "url": "https://www.johndoe.com",
  "sameAs": [
    "https://www.linkedin.com/in/johndoe",
    "https://twitter.com/johndoe"
  ]
}
</script>

Not too bad, right? This example is for a personal CV page that includes links to John Doe’s social media profiles. Keep in mind that different pages on your website will require different kinds of JSON-LD data, depending on their content.

Implementing JSON-LD in Next.js

Now that you’ve got a handle on the basics, let’s integrate JSON-LD into a Next.js application. We’ll create a reusable React component for embedding JSON-LD data. First, install the schema-dts library to help with TypeScript types:

npm install schema-dts

Next, create the JsonLd component:

import { FC } from 'react';
import { Thing, WithContext } from 'schema-dts';

type Props<T extends Thing> = {
  data: WithContext<T>;
};

const JsonLd: FC<
  Props<
    Thing & {
      '@context': 'https://schema.org';
    }
  >
> = ({ data }) => {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
    />
  );
};

export default JsonLd;

This component allows you to pass any structured data object, ensuring it’s properly formatted and injected into your Next.js pages.

Where to Use the JSON-LD Component

Now that your JsonLd component is ready, you can use it throughout your application. For example, let’s add structured data to the homepage of a restaurant in src/app/page.tsx:

import { FC } from 'react';
import JsonLd from '../components/JsonLd'; // Adjust the import path as necessary
import { Restaurant, WithContext } from 'schema-dts';

const RestaurantPage: FC = () => {
  const restaurantJsonLd: WithContext<Restaurant> = {
    '@type': 'Restaurant',
    '@context': 'https://schema.org',
    name: 'The Gourmet Kitchen',
    address: {
      '@type': 'PostalAddress',
      streetAddress: '123 Delicious Ave',
      addressLocality: 'Food City',
      addressRegion: 'FC',
      postalCode: '12345',
      addressCountry: 'US',
    },
    telephone: '+1-800-555-1234',
    openingHours: ['Mo-Sa 11:00-22:00', 'Su 12:00-20:00'],
    hasMenu: {
      '@type': 'Menu',
      name: 'Main Menu',
      hasMenuSection: [
        {
          '@type': 'MenuSection',
          name: 'Pizza',
          hasMenuItem: [
            {
              '@type': 'MenuItem',
              name: 'Margherita Pizza',
              offers: {
                '@type': 'Offer',
                priceCurrency: 'USD',
                price: '12.99',
              },
            },
          ],
        },
        {
          '@type': 'MenuSection',
          name: 'Salads',
          hasMenuItem: [
            {
              '@type': 'MenuItem',
              name: 'Caesar Salad',
              offers: {
                '@type': 'Offer',
                priceCurrency: 'USD',
                price: '8.99',
              },
            },
          ],
        },
        {
          '@type': 'MenuSection',
          name: 'Pasta',
          hasMenuItem: [
            {
              '@type': 'MenuItem',
              name: 'Spaghetti Bolognese',
              offers: {
                '@type': 'Offer',
                priceCurrency: 'USD',
                price: '14.99',
              },
            },
          ],
        },
      ],
    },
  };

  return (
    <>
      <h1>The Gourmet Kitchen</h1>
      <p>
        Welcome to The Gourmet Kitchen! Enjoy our exquisite dishes made with
        love.
      </p>

      {/* Insert the JSON-LD data for the restaurant */}
      <JsonLd data={restaurantJsonLd} />
    </>
  );
};

export default RestaurantPage;

Not a Restaurant Owner?

No worries! JSON-LD isn’t limited to restaurants. You can find supported schemas for various types of businesses and entities on the schema.org website. They even provide a search tool to help you find the appropriate schema for your needs—how cool is that?

Wrapping Up

By implementing JSON-LD structured data, you’re taking a significant step toward improving your website’s SEO and enriching your search results. While this doesn’t guarantee instant results, it’s a powerful tool in making your content more accessible and attractive to search engines.

And hey, you’ve made it this far—here’s a virtual avocado 🥑 for your efforts. Keep up the great work, and your website will be all the better for it!

RSS Feed with Next.js 14 and App Router

Drazen Bebic — Wed, 28 Aug 2024 20:39:13 +0000

Note: This guide still works with both Next.js 15 and 16!

Creating an RSS feed for your NextJS applications is easy peasy. The really "difficult" part lies with fetching the data and transforming it before it's passed to the RSS feed. This is especially true if you need to modify the data first (if the blog posts come in a Markdown format for example).

But to keep this guide simple, we will only focus on creating the RSS feed itself. So without further ado, this is how we do it:

Dependencies

Install the rss package with the package manager of your choice.

yarn add rss

npm install rss

pnpm add rss

feed.xml

Create the following file in your project: src/app/feed.xml/route.ts. This will allow us to handle the request for the /feed.xml URL of our website server-sided, without any React components.

Your route.ts should look a little like this:

import RSS from 'rss';

export async function GET() {
  // First we will add some basic blog info.
  const feed = new RSS({
    title: "Drazen's Tech Blog",
    description: 'I do stuff.',
    generator: 'RSS for Node and Next.js',
    feed_url: 'https://drazen.bebic.dev/feed.xml',
    site_url: 'https://drazen.bebic.dev',
    managingEditor: 'drazen@bebic.at (Drazen Bebic)',
    webMaster: 'drazen@bebic.at (Drazen Bebic)',
    copyright: 'Copyright 2024, Drazen Bebic',
    language: 'en-US',
    pubDate: new Date().toUTCString(),
    ttl: 60,
  });

  // Then we will add our individual blog posts. You can of course
  // fetch these from somewhere else.
  feed.item({
    title: 'Blog Post #1',
    description: 'Description of Blog Post #1',
    url: `https://drazen.bebic.dev/blog/blog-post-1`,
    categories: ['nextjs', 'blog'],
    author: 'Drazen Bebic',
    date: '2024-08-27',
  });
  feed.item({
    title: 'Blog Post #2',
    description: 'Description of Blog Post #2',
    url: `https://drazen.bebic.dev/blog/blog-post-2`,
    categories: ['nextjs', 'blog'],
    author: 'Drazen Bebic',
    date: '2024-08-28',
  });

  // And finally, we return a response with the appropriate
  // Content-Type header.
  return new Response(feed.xml({ indent: true }), {
    headers: {
      'Content-Type': 'application/xml; charset=utf-8',
    },
  });
}

Accessing the route

Simply access the /feed.xml route of your application, you should see something like this:

And that's something that RSS feed readers can work with. I use this to crosspost my blog to Dev.to (Hi dev.to readers! 👋).

Self-Hosted WordPress Plugin Updates

Drazen Bebic — Tue, 28 May 2024 22:04:08 +0000

So you developed your own plugin and now want to monetize on it. Since it's not free, you can't use the WordPress Plugin Repository for this purpose because it only supports free plugins. You will need to either host it on a marketplace or host it yourself. If you chose the latter and don't know how, then this guide is for you.

What will we be doing?

It takes a solid amount of effort, but it's not too complex. It basically boils down to two things:

Client - Point your WordPress plugin to your own server for updates
Server - Build & deploy an update server to handle said updates

The first point is rather simple. It takes a couple of hooks to modify your plugin in such a way that it points to a custom server for plugin updates.

The most effort lies in developing an update server which makes sense for you. This is also the part that is up to you on how to design it, since there is no single approach that will work for everyone. For the sake of simplicity, I have developed this as a WordPress plugin. In the past I also used an app built on the PERN stack. Anything goes.

The Client Plugin

I have created a simple plugin where everything is located in the main plugin file. Of course you can split this up into separate files, use classes, composer with autoloading, etc. But for simplicity's sake we will throw everything into one pot 🍲

Preparation

Before we start with the actual code, let's define some constants to make our life a little bit easier.

/*
Plugin Name: Self-Hosted WordPress Plugin Updates - Client
Description: Demo plugin showcasing a client plugin which updates from a custom update server.
Version: 1.0.0
Author: Drazen Bebic
Author URI: https://drazen.bebic.dev
Text Domain: shwpuc
Domain Path: /languages
*/

// Current plugin version.
define( "SHWPUC_PLUGIN_VERSION", "1.0.0" );

// Output of this will be
// "self-hosted-plugin-updates/self-hosted-plugin-updates.php".
define( "SHWPUC_PLUGIN_SLUG", plugin_basename( __FILE__ ) );

// Set the server base URL. This should
// be replaced with the actual URL of
// your update server.
define( "SHWPUC_API_BASE_URL", "https://example.com/wp-json/shwpus/v1" );

/**
 * Returns the plugin slug: self-hosted-plugin-updates
 *
 * @return string
 */
function shwpuc_get_plugin_slug() {
    // We split this string because we need the
    // slug without the fluff.
    list ( $t1, $t2 ) = explode( '/', SHWPUC_PLUGIN_SLUG );

    // This will remove the ".php" from the
    // "self-hosted-plugin-updates.php" string
    // and leave us with the slug only.
    return str_replace( '.php', '', $t2 );
}

We defined a new plugin, constants for the plugin version, slug, and the base URL of our update server. Another thing we added is a function to retrieve the plugin slug, without the ".php" ending.

Package download

The very first thing we want to do is to add a filter to the pre_set_site_transient_update_plugins hook. We will modify the response for our plugin so that it checks the remote server for a newer version.

/**
 * Add our self-hosted auto-update plugin
 * to the filter transient.
 *
 * @param $transient
 *
 * @return object $transient
 */
function shwpuc_check_for_update( $transient ) {
    // This will be "self-hosted-plugin-updates-client"
    $slug = shwpuc_get_plugin_slug();

    // Set the server base URL. This should be replaced
    // with the actual URL of your update server.
    $api_base = SHWPUC_API_BASE_URL;

    // This needs to be obtained from the
    // site settings. Somewhere set by a
    // setting your plugin provides.
    $license_i_surely_paid_for = 'XXX-YYY-ZZZ';

    // Get the remote version.
    $remote_version = shwpuc_get_remote_version( $slug );

    // This is the URL the new plugin
    // version will be downloaded from.
    $download_url = "$api_base/package/$slug.$remote_version.zip?license=$license_i_surely_paid_for";

    // If a newer version is available, add the update.
    if ( $remote_version
        && version_compare( SHWPUC_PLUGIN_VERSION, $remote_version, '<' )
    ) {
        $obj              = new stdClass();
        $obj->slug        = $slug;
        $obj->new_version = $remote_version;
        $obj->url         = $download_url;
        $obj->package     = $download_url;

        $transient->response[ SHWPUC_PLUGIN_SLUG ] = $obj;
    }

    return $transient;
}

// Define the alternative API for updating checking
add_filter( 'pre_set_site_transient_update_plugins', 'shwpuc_check_for_update' );

This function alone already does quite a lot of the heavy lifting, it...

Retrieves the latest plugin version from the remote server.
Checks if the remote version is greater than the currently installed version.
Passes the license URL parameter to the download link.
Stores update information into the transient if there is a newer version available.

Version Check

You probably noticed the shwpu_get_remote_version() function, so let's get into that now.

/**
 * Return the latest version of a plugin on
 * the remote update server.
 *
 * @return string|null $remote_version
 */
function shwpuc_get_remote_version( $slug ) {
    $api_base = SHWPUC_API_BASE_URL;
    $license  = 'XXX-YYY-ZZZ';
    $url      = "$api_base/version/$slug?license=$license";
    $request  = wp_remote_get( $url );

    if ( ! is_wp_error( $request )
         || wp_remote_retrieve_response_code( $request ) === 200
    ) {
        return $request['body'];
    }

    return null;
}

Pretty straightforward: Send the request and pass on the response.

Plugin Information

Now our plugin knows that there is a new version, but what about the "What's new?" section and the changelog for this new fancy-pants version? Gues what? We need another hook for this.

/**
 * Add our self-hosted description to the filter
 *
 * @param boolean  $false
 * @param array    $action
 * @param stdClass $arg
 *
 * @return bool|stdClass
 */
function shwpuc_check_info( $false, $action, $arg ) {
    // This will be "self-hosted-plugin-updates"
    $slug = shwpuc_get_plugin_slug();

    // Abort early if this isn't our plugin.
    if ( $arg->slug !== $slug ) {
        return false;
    }

    // Set the server base URL. This should be replaced
    // with the actual URL of your update server.
    $api_base = SHWPUC_API_BASE_URL;
    $license  = 'XXX-YYY-ZZZ';
    $url      = "$api_base/info/$slug?license=$license";
    $request  = wp_remote_get( $url );

    if ( ! is_wp_error( $request )
        || wp_remote_retrieve_response_code( $request ) === 200
    ) {
        return unserialize( $request['body'] );
    }

    return null;
}

// Define the alternative response for information checking
add_filter( 'plugins_api', 'shwpuc_check_info', 10, 3 );

This hook will trigger when you go to check the changelog of the newly available update for your plugin. Your update server needs to return information about the new version, like the description, changelog, and anything else you think is important to know.

The Update Server

Now that we covered the basics about what the client plugin should do, let's do the same for the update server. Like I said before, this part leaves a lot more room for interpretation, because it is a 3rd party application which you can design and run on anything you want. You only need to make sure that the response is compatible with WordPress.

For this demo, I decided to use a simple WordPress plugin which you would install on a regular WordPress instance. This WordPress instance will then act as your plugin update server.

Important: The client and server plugin will not work on the same WordPress instance! When the client tries to perform the update, it will automatically turn on maintenance mode on the WordPress instance, which disables the REST API, which makes the download of the new package version fail.

API routes

This server plugin will have to provide a handful of API routes which we have previously mentioned in the client plugin, and those are:

/v1/version/:plugin - Used to check the latest version of the plugin.
/v1/info/:plugin - Used to check the information about the latest version of the plugin.
/v1/package/:plugin - Used to download the latest version of the plugin.

Registering the routes

The very first thing you need to do is to register the necessary REST API routes with WordPress. We will register one route for every endpoint mentioned previously. Pretty straightforward:

/**
 * Registers the routes needed by the plugins.
 *
 * @return void
 */
function shwpus_register_routes() {
    register_rest_route(
        'shwpus/v1',
        '/version/(?P<plugin>[\w-]+)',
        array(
            array(
                'methods'             => WP_REST_Server::READABLE,
                'callback'            => 'shwpus_handle_plugin_version_request',
                'permission_callback' => 'shwpus_handle_permission_callback',
                'args'                => array(
                    'plugin' => array(
                        'description' => 'The plugin slug, i.e. "my-plugin"',
                        'type'        => 'string',
                    ),
                ),
            ),
        )
    );

    register_rest_route(
        'shwpus/v1',
        '/info/(?P<plugin>[\w-]+)',
        array(
            array(
                'methods'             => WP_REST_Server::READABLE,
                'callback'            => 'shwpus_handle_plugin_info_request',
                'permission_callback' => 'shwpus_handle_permission_callback',
                'args'                => array(
                    'plugin' => array(
                        'description' => 'The plugin slug, i.e. "my-plugin"',
                        'type'        => 'string',
                    ),
                ),
            ),
        )
    );

    register_rest_route(
        'shwpus/v1',
        '/package/(?P<plugin>[\w.-]+)',
        array(
            array(
                'methods'             => WP_REST_Server::READABLE,
                'callback'            => 'shwpus_handle_plugin_package_request',
                'permission_callback' => 'shwpus_handle_permission_callback',
                'args'                => array(
                    'plugin' => array(
                        'description' => 'The plugin slug with the version, ending in .zip, i.e. "my-plugin.2.0.0.zip"',
                        'type'        => 'string',
                    ),
                ),
            ),
        )
    );
}

Permission Callback

You'll notice that I set the permission_callback to shwpus_handle_permission_callback. This function checks whether the license your client passed along is valid, so you know that the client is actually authorized for future updates.

You could also remove this check for the version and info routes, so that everyone gets notified about new version and knows what's new, but only the customers with valid licenses can actually update. To do this simply set the permission_callback to __return_true, which is a WordPress utility function which returns true right away.

Here's how our permission callback function looks like:

/**
 * @param WP_REST_Request $request
 *
 * @return true|WP_Error
 */
function shwpus_handle_permission_callback( $request ) {
    $slug = $request->get_param( 'plugin' );
    $license = $request->get_param( 'license' );

    if ( $license !== 'XXX-YYY-ZZZ' ) {
        return new WP_Error(
            401,
            'Invalid license',
            array(
                'slug' => $slug,
                'license' => $license
            )
        );
    }

    return true;
}

Check the version

This route fetches the latest version of the given plugin from your database or whatever else you have. It needs to return it as text/html with nothing but the version number as a response.

/**
 * Finds the latest version for a given plugin.
 *
 * @param WP_REST_Request $request
 *
 * @return void
 */
function shwpus_handle_plugin_version_request( $request ) {
    // Retrieve the plugin slug from the
    // request. Use this slug to find the
    // latest version of your plugin.
    $slug = $request->get_param( 'plugin' );

    // This is hardcoded for demo purposes.
    // Normally you would fetch this from
    // your database or whatever other
    // source of truth you have.
    $version = '1.0.1';

    header('Content-Type: text/html; charset=utf-8');
    echo $version;
    die();
}

After you've done that, your plugin should be able to tell you that there's a new version.

Plugin Information

This is where it gets interesting. This route needs to return the plugin information in a specific structure as a serialized PHP object. If you're using Node.js don't worry - there is a nifty npm package called php-serialize which will let you do just that.

Since we're using PHP, there's no need for that and we can just call the PHP native serialize() function.

/**
 * Fetches information about the latest version
 * of the plugin with the given slug.
 *
 * @param WP_REST_Request $request
 *
 * @return void
 */
function shwpus_handle_plugin_info_request( $request ) {
    $slug    = $request->get_param( 'plugin' );
    $version = '1.0.1';

    // This data should be fetched dynamically
    // but for demo purposes it is hardcoded.
    $info = new stdClass();
    $info->name = 'Self-Hosted WordPress Plugin Updates - Client';
    $info->slug = 'self-hosted-plugin-updates-client';
    $info->plugin_name = 'self-hosted-plugin-updates-client';
    $info->new_version = $version;
    $info->requires = '6.0';
    $info->tested = '6.5.3';
    $info->downloaded = 12540;
    $info->last_updated = '2024-05-23';
    $info->sections = array(
        'description' => '
            <h1>Self-Hosted WordPress Plugin Updates - Client</h1>
            <p>
                Demo plugin showcasing a client plugin
                which updates from a custom update
                server.
            </p>
        ',
        'changelog' => '
            <h1>We did exactly 3 things!</h1>
            <p>
                You thought this is going to be a huge update.
                But it\'s not. Sad face.
            </p>
            <ul>
                <li>Added a cool new feature</li>
                <li>Added another cool new feature</li>
                <li>Fixed an old feature</li>
            </ul>
        ',
        // You can add more sections this way.
        'new_tab' => '
            <h1>Woah!</h1>
            <p>We are so cool, we know how to add a new tab.</p>
        ',
    );
    $info->url = 'https://drazen.bebic.dev';
    $info->download_link = get_rest_url( null, "/shwpus/v1/package/$slug.$version.zip" );

    header('Content-Type: text/html; charset=utf-8');
    http_response_code( 200 );
    echo serialize( $info );
    die();
}

This should make your changes in the frontend visible.

Package Download

This is where your plugin will be downloaded from. For demo purposes I simply put the plugin .zip files in a packages directory which I put into wp-content. You can of course integrate whatever other file storage you have and fetch your plugin zips from there.

/**
 * @param WP_REST_Request $request
 *
 * @return void
 */
function shwpus_handle_plugin_package_request( $request ) {
    // Contains the plugin name, version, and .zip
    // extension. Example:
    // self-hosted-plugin-updates-server.1.0.1.zip
    $plugin = $request->get_param( 'plugin' );

    // The packages are located in wp-content for
    // demo purposes.
    $file = WP_CONTENT_DIR . "/packages/$plugin";

    if ( ! file_exists( $file ) ) {
        header( 'Content-Type: text/plain' );
        http_response_code( 404 );
        echo "The file $file does not exist.";
        die();
    }

    $file_size = filesize( $file );

    header( 'Content-Type: application/octet-stream' );
    header( "Content-Length: $file_size" );
    header( "Content-Disposition: attachment; filename=\"$plugin\"" );
    header( 'Access-Control-Allow-Origin: *' );
    http_response_code( 200 );
    readfile( $file );
    die();
}

And last but not least, your plugin can now be fully updated!

Conclusion

Hosting your own plugin update server is very much doable. The complexity increases with your requirements for the "backend" administration. If you need a UI then you will need to expand on the server part quite a lot.

The client part is pretty easy and straightforward, there's not much that you need to do except add a few hooks. You could go a step further and disable the plugin if there is no valid license present.

Resources

I added the source code for these two plugins into two comprehensive GitHub gists.

PHP Code Sniffer with WordPress Coding Standard

Drazen Bebic — Mon, 13 May 2024 07:13:00 +0000

Tired of WordPress core nagging you about coding style inconsistencies in your plugins or themes? Fear not! This guide will walk you through setting up PHP CodeSniffer (PHPCS) with the WordPress Coding Standard (WPCS). Get ready to write clean, consistent, and future-proof WordPress code that adheres to best practices. Let's dive in!

Setting up Composer

The first thing you need to do is install Composer if you don't have it already. I'm not going to go into great detail about how to install composer since it's already documented on their website.

After that, navigate to the root fo your project and create a composer.json file (if you don't have it already) by typing composer init.

WordPress Coding Standard

After you have installed Composer and have a composer.json in your project root type the following commands:

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

composer require --dev wp-coding-standards/wpcs

Custom Configuration File

Create a phpcs.xml file in the project root. Here's an example configuration you can use as a template:

PHP Code Sniffer Configuration File for WordPress

Composer Scripts

In this example we have added two scripts: lint and lint:fix. The lintcommand shows all linting errors and warnings present in the configured files, while the lint:fix command tries to automatically fix errors which it can fix.

Important : The lint:fix command can't fix all commands the lintcommand can find. These changes need to be fixed manually. Also: don't forget to add the .phpcs.cache folder to your .gitignore file.

{
  "scripts": {
    "lint": "./vendor/bin/phpcs --standard=phpcs.xml",
    "lint:fix": "./vendor/bin/phpcbf --standard=phpcs.xml"
  }
}

Additional Steps

Once you've completed the steps you're pretty much done. You can now use the scripts to check your code for inconsistencies and fix errors.

You could add the composer lint command to your pre-commit hooks or to your CI/CD workflows to ensure that no un-linted code slips through the cracks.

Forem: Drazen Bebic

Image Optimization with Next.js and Sanity.io

Introduction

New Image Component

Custom Image Loader

Utility Functions

Prerequisites

Configuring Next.js

Defining the Sanity Schema

Updating the GROQ Query

Step 1: The Builder Utilities

Step 2: The Sanity Loader

Step 3: The Wrapper Component

Step 4: The sizes Property

Conclusion

How to Add Settings Pages to WordPress Plugins: A Developer's Guide

The Goal

Prerequisites

Step 1: Registering the Menu Item

Step 2: Registering the Setting

Step 3: Rendering the Settings Page

Step 4: Connecting the Logic

Conclusion

How to Create Your First WordPress Plugin: A Developer's Guide

What Actually is a WordPress Plugin?

Prerequisites

Step 1: The Folder Structure

Step 2: The Plugin Header

Step 3: Understanding Hooks (Actions vs. Filters)

Step 4: Building the Logic

Step 5: Adding Settings (Optional but Recommended)

Conclusion

What is JSON-LD? A Developer's Guide to Structured Data

What is JSON-LD?

Why JSON-LD is the Winner for SEO

Core Syntax and Structure

Nesting Objects

Moving from Theory to Practice

Validation and Debugging

Automated Testing

Conclusion

Unleash Your Inner Avenger: A Beginner's Guide to Unix Shells

What Exactly Is a Shell?

Shell vs. Terminal: What's the Difference?

Common Unix Shells Explained

Bourne Shell (sh)

Bourne-Again Shell (bash)

Z Shell (zsh)

Korn Shell (ksh)

Tenex C Shell (tcsh)

Customizing Your Shell

Understanding Shell Configuration Files

Modern Shells and Tools

Conclusion

What Did I Do? A Time-Tracking Problem

I am lazy

But I am a developer, too

You can hold a job?

Linking Private GitHub Repositories as Composer Dependencies

Creating our Package

GitHub Repository

Composer Initialization

Versioning

Consuming in a Public Repository

Consuming in a Private Repository

Create a GitHub PAT

Local Authentication

Workflow Authentication

Wrapping up

Optimizing and Cleaning Up Your WordPress Database: A DIY Guide

Backup first - It's Critical!

Plugin Alternatives

What Are We Cleaning?

Enhancing Database Performance

Ready to Clean?

Optimization Query

Cleanup Query

Rollback If Something Goes Wrong

Conclusion

Enhance Your SEO with JSON-LD: A Practical Guide

Bourne Shell (`sh`)

Bourne-Again Shell (`bash`)

Z Shell (`zsh`)

Korn Shell (`ksh`)

Tenex C Shell (`tcsh`)