PHPackages                             justintadlock/hybrid-carbon - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. justintadlock/hybrid-carbon

ActiveLibrary[Utility & Helpers](/categories/utility)

justintadlock/hybrid-carbon
===========================

God-like post featured image script.

1.0.0(7y ago)202.6k2[1 issues](https://github.com/themehybrid/hybrid-carbon/issues)[1 PRs](https://github.com/themehybrid/hybrid-carbon/pulls)GPL-2.0-or-laterPHPPHP >=5.6

Since Sep 14Pushed 3y ago9 watchersCompare

[ Source](https://github.com/themehybrid/hybrid-carbon)[ Packagist](https://packagist.org/packages/justintadlock/hybrid-carbon)[ Docs](https://github.com/justintadlock/hybrid-carbon)[ RSS](/packages/justintadlock-hybrid-carbon/feed)WikiDiscussions master Synced 4d ago

READMEChangelogDependenciesVersions (3)Used By (0)

Hybrid\\Carbon
==============

[](#hybridcarbon)

Post featured image script with magical properties.

Hybrid Carbon is a drop-in library. It is not a standalone plugin and should be included in any themes/plugins that you ship.

This is a refresh of the original [Get the Image](https://github.com/justintadlock/get-the-image) project to make it more suitable for including in both plugins and themes as a drop-in package. It's also a way to shed some of the 10+ years of baggage from the original plugin.

Hybrid Carbon is meant to replace the core WP featured image (i.e., post thumbnail) feature with a version that has a few more possibilities. Out of the box, it comes with 4 methods for locating featured images:

- `featured` - This is the normal featured/thumbnail image.
- `attached` - Searches for the first image uploaded/attached to a post.
- `meta` - Searches for an image (attachment ID) assigned to a custom meta field.
- `scan` - Scans the post content for image attachment IDs.

All of the core script methods are based around core WP's image attachment feature so that we can utilize the built-in functions already available like responsive images using `srcset` and `sizes`.

Requirements
------------

[](#requirements)

- PHP 5.6+ (preferably 7+)
- [Composer](https://getcomposer.org/) for managing PHP dependencies.

Documentation
-------------

[](#documentation)

The script should be relatively easy to use if you've ever worked with featured images in WP. There's not a lot of code to change. The following docs are written with theme authors in mind because that'll be the most common use case. If including in a plugin, it shouldn't be much different.

### Installation

[](#installation)

First, you'll need to open your command line tool and change directories to your theme folder.

```
cd path/to/wp-content/themes/
```

Then, use Composer to install the package.

```
composer require justintadlock/hybrid-carbon
```

Assuming you're not already including the Composer autoload file for your theme and are shipping this as part of your theme package, you'll want something like the following bit of code in your theme's `functions.php` to autoload this package (and any others).

The Composer autoload file will automatically load up Hybrid Carbon for you and make its code available for you to use.

```
if ( file_exists( get_parent_theme_file_path( 'vendor/autoload.php' ) ) ) {
	require_once( get_parent_theme_file_path( 'vendor/autoload.php' ) );
}
```

### Usage

[](#usage)

Most developers will want to utilize the `Hybrid\Carbon\Image` class. It is a static wrapper class that essentially acts as *syntactic sugar* for use in theme templates.

Typically, you'd want to replace any calls to `the_post_thumbnail()` inside of The Loop in your theme templates like so:

```
Hybrid\Carbon\Image::display( 'featured', $args );
```

*Note that the plugin's namespace is `Hybrid\Carbon`. If you're working within another namespace, you'll want to add a `use` statement after your own namespace call or call `\Hybrid\Carbon\display()` directly. I'll assume you know what you're doing if you're working with namespaces. Otherwise, stick to the above.*

### Parameters

[](#parameters)

There are two parameters: `$type` and `$args`.

```
Hybrid\Carbon\Image::display( $type, $args );
```

**$type**

The `$type` parameter accepts a string of a single type or an array of types. A type is just the method to use to locate a featured image.

The following are the built-in types:

- `featured` - This is the normal featured/thumbnail image.
- `attached` - Searches for the first image uploaded/attached to a post.
- `meta` - Searches for an image (attachment ID) assigned to a custom meta field. Must be coupled with a `meta_key` set in `$args`.
- `scan` - Scans the post content for image attachment IDs.

If passing in an array of types, the script will search for images in the order that you add them.

**$args**

The `$args` parameter is an optional array of arguments to customize the image.

- `post_id` - ID of the post to get the image for (defaults to current post).
- `size` - Size of the image to get.
- `meta_key` - String or array of meta keys to search for (value must be an attachment ID).
- `class` - Class applied to the image.
- `link` - Whether to link to the post.
- `link_class` - Class applied to the link.
- `min_width` - Minimum width required of the image.
- `min_height` - Minimum height required of the image.
- `attr` - Array of image attributes.
- `caption` - Whether to include captions for images that have them (defaults to `false`).
- `before` - HTML string to add before the output of the image.
- `after` - HTML string to add after the output of the image.

### Static helper class

[](#static-helper-class)

The following methods are available for the `Hybrid\Carbon\Image` class.

```
// Returns an instance of the Carbon class.
Image::carbon( $type, array $args = [] );

// Returns an instance of the Carbon class after running its make() method.
Image::make( $type, array $args = [] );

// Returns an instance of the found Image object or false.
Image::image( $type, array $args = [] );

// Renders the HTML output of the found Image object if one is found.
Image::display( $type, array $args = [] );

// Returns the HTML string of the found Image object or an empty string.
Image::render( $type, array $args = [] );
```

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity26

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

2849d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ef868a4b45ef0263f49361744b8bb04e8f3cfcb8f3f79b274fc62823115ee596?d=identicon)[justintadlock](/maintainers/justintadlock)

---

Top Contributors

[![justintadlock](https://avatars.githubusercontent.com/u/1816309?v=4)](https://github.com/justintadlock "justintadlock (40 commits)")

---

Tags

wordpress

### Embed Badge

![Health badge](/badges/justintadlock-hybrid-carbon/health.svg)

```
[![Health](https://phpackages.com/badges/justintadlock-hybrid-carbon/health.svg)](https://phpackages.com/packages/justintadlock-hybrid-carbon)
```

###  Alternatives

[tgmpa/tgm-plugin-activation

TGM Plugin Activation is a PHP library that allows you to easily require or recommend plugins for your WordPress themes (and plugins).

1.8k230.2k13](/packages/tgmpa-tgm-plugin-activation)[aristath/kirki

Extending the WordPress customizer

1.3k73.1k4](/packages/aristath-kirki)[afragen/git-updater

A plugin to automatically update GitHub, Bitbucket, GitLab, or Gitea hosted plugins, themes, and language packs.

3.3k1.7k](/packages/afragen-git-updater)[tacowordpress/tacowordpress

WordPress custom post types that feel like CRUD models

232.2k](/packages/tacowordpress-tacowordpress)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)