README

OG

一个纯PHP编写的OpenGraph图像生成器，因此您无需在任何地方安装另一个运行时或整个浏览器实例，只需创建一个动态PNG。

赞助

OG可以免费用于个人或商业用途。如果它使您的工作更容易，或者您只是想确保它继续得到支持和改进，我真的很感激您的捐赠！

如果您正在使用OG，我非常想看到您的作品！请通过推特/toot（@simonhamp，@simonhamp@phpc.social）发送一些链接，这样我就可以看到您如何在野外使用OG。

谢谢 🙏

赞助商

Laradir - 将最好的Laravel开发者与最好的Laravel团队连接起来。
quantumweb - 一家裸机网络机构。更少的层次，更好的结果。
RedGalaxy - 一家位于剑桥郡的网络应用开发工作室，致力于帮助业务提高效率和盈利能力。
Sevalla - 在单一、直观的平台中托管和管理您的应用程序、数据库和静态站点。

安装

通过Composer安装

composer require simonhamp/the-og

使用

使用OG非常简单。这里有一个基本示例

use SimonHamp\TheOg\Background;
use SimonHamp\TheOg\Image;

(new Image())
    ->accentColor('#cc0000')
    ->border()
    ->url('https://example.com/blog/some-blog-post-url')
    ->title('Some blog post title that is quite big and quite long')
    ->description(<<<'TEXT'
        Some slightly smaller but potentially much longer subtext. It could be really long so we might need to trim it completely after many words.

        Some slightly smaller but potentially much longer subtext. It could be really long so we might need to trim it completely after many words.
    TEXT)
    ->background(Background::JustWaves, 0.2)
    ->save(__DIR__.'/test.png');

这是生成的图像

Image类提供了一个优雅且流畅的API，用于配置图像的内容、样式和布局，以及渲染图像并将其保存到文件的辅助工具。

检查您的图像

想看看您的图像在社交媒体上分享时的样子吗？请查看SEOToolkit的社交分享预览

存储图像

方便的是，您可以使用save()方法将图像存储在本地文件系统上

$image = new Image;
$image->save('/path/to/your/image.png');

如果您更喜欢将图像存储在本地文件系统之外的地方（例如在Amazon S3上存储），您可以使用toString()方法。

toString()将返回作为二进制字符串的渲染图像

$image = (new Image())->toString();

// $service here could be an AWS\S3\S3Client, for example
$service->putObject([
    'Key' => 'example-image.png',
    'Body' => $image,
    'ContentType' => 'image/png',
]);

这将直接将原始二进制数据发送到外部服务，而无需先在本地磁盘上写入图像文件。

图像格式

默认情况下，OG以PNG格式编码图像。

但是，如果您想使用不同的格式，也可以！只需将相关intervention/image编码器的实例传递给save()或toString()方法即可。

use Intervention\Image\Encoders\WebpEncoder;

$image->toString(encoder: new WebpEncoder);

颜色

在OG中，颜色可以用十六进制代码、rgba或HTML命名颜色表示。

背景

OG附带了一些内置的背景图案，您可以使用这些图案为您的图像添加一些纹理。您可以在Background枚举中找到所有这些。

背景可以设置为重复或覆盖，并且还具有不透明度。

use SimonHamp\TheOg\Background;
use SimonHamp\TheOg\BackgroundPlacement;

(new Image)->background(
    background: Background::JustWaves,
    opacity: 0.5,
    placement: BackgroundPlacement::Cover
);

它还支持从本地或远程源自定义背景图片。请参阅下文的自定义背景图片部分。

边框

边框通过用单色带包围图像的一个或多个边缘来为您的图像提供微妙的颜色和纹理变化——通常是主题的 accentColor。

边框通常作为主题的一部分定义，但您可以在图像本身上覆盖边框位置、颜色和大小

use SimonHamp\TheOg\BorderPosition;

$image = new Image;
$image->border(BorderPosition::Top, 'pink', 10);

可用的边框位置有

BorderPosition::All - 所有4个边缘都将被边框包围
BorderPosition::Bottom - 底边缘将被边框包围
BorderPosition::Left - 左边缘将被边框包围
BorderPosition::Right - 右边缘将被边框包围
BorderPosition::None - 没有边缘将被边框包围
BorderPosition::Top - 顶部边缘将被边框包围
BorderPosition::X - 结合BorderPosition::Top和BorderPosition::Bottom
BorderPosition::Y - 结合BorderPosition::Left和BorderPosition::Right

移除默认边框

您可以通过将border()方法与设置为BorderPosition::None的position参数连用，从图像中移除默认边框

$image = new Image;
$image->border(BorderPosition::None);

主题

主题设置您的图像的颜色、字体和样式。目前有2个主题可供选择：Light和Dark。

默认主题是Light。

您可以在渲染图像之前任何时候设置图像的主题

use SimonHamp\TheOg\Theme;

$image = new Image;
$image->theme(Theme::Dark);

创建主题

主题是实现了Theme接口的简单类。

然而，您可以通过简单地实例化Theme类来最轻松地创建自己的主题

use SimonHamp\TheOg\Theme\Fonts\Inter;
use SimonHamp\TheOg\Theme\Theme;

$theme = new Theme(
    accentColor: '#247BA0',
    backgroundColor: '#ECEBE4',
    baseColor: '#153B50',
    baseFont: Inter::bold(),
    callToActionBackgroundColor: '#153B50',
    callToActionColor: '#ECEBE4',
    descriptionColor: '#429EA6',
    descriptionFont: Inter::light(),
    titleFont: Inter::black(),
);

$image = new Image;
$image->theme($theme);

字体

目前有2种字体可用（每种有4种变体）

如果您认为某个字体添加到该软件包的核心部分是有意义的，请考虑贡献并提交一个Pull Request。

自定义字体

您可以通过创建一个实现了Font接口的类来加载自定义字体

use SimonHamp\TheOg\Interfaces\Font;

class CustomFont implements Font
{
    public function path(): string
    {
        return '/path/to/your/font/source/file.ttf';
    }
}

然后您可以在定义您的主题时加载此字体

$font = new CustomFont;

$theme = new Theme(
    baseFont: $font,
);

自定义背景图片

如果内置的背景图案无法满足您的需求，您可以简单地通过实例化Background类来加载自己的背景图片

use SimonHamp\TheOg\Theme\Background;

$background = new Background('/path/to/your/image.png');

然后您可以将背景传递到您的自定义主题中，或者直接传递到您的图像中

$theme = new Theme(
    background: $background,
);

$image = (new Image)->theme($theme);

// Or

$image->background($background);

如果您想要更多自定义背景，您可以创建自己的背景类，实现Background接口。

覆盖主题设置

您可以通过不创建全新主题，覆盖一些主题设置，如强调颜色、背景和背景颜色。

$image = new Image;
$image->backgroundColor('seagreen')
    ->background($customBackground);

布局

虽然主题控制图像中使用的颜色和样式，但布局控制图像的大小以及图像元素（文本块、其他图像等）的大小和位置，称为功能。

不同的布局提供不同的功能。

目前有3种布局

默认布局是Standard。

还将有更多布局推出。

创建布局

布局是简单的类，具有一些基本设置和用于定义图像所有特征的 features() 方法。

每个布局类必须实现 Layout 接口

查看标准布局或任何其他内置布局作为示例。

在其中，您将看到布局的基本设置，例如画布的尺寸、边框大小和位置以及任何填充。

所有尺寸均以像素为单位。

功能

功能是构成您的图像的单独元素，例如标题、描述、URL 等。

所有布局 都支持背景（始终首先渲染）和边框（始终最后渲染），因此您通常不需要将这些定义为不同的功能。

除此之外，图像的功能完全由布局定义。它们定义的顺序决定了它们的渲染顺序和，因此，它们的层次。

可用内置功能

TextBox 允许您渲染一个受限的文本块。框的大小用于限制文本；框的最终大小由渲染文本的长度、字体、大小和行高决定。
PictureBox 允许您渲染图像。

查看内置布局以了解如何使用这些功能并将它们添加到布局中。

定位功能

功能可以在画布上的任何绝对位置或相对于画布上的另一个功能进行定位。

要使用相对定位，为您的目标功能提供一个独特的名称很有帮助，该名称在其他功能需要引用其最终渲染位置时使用。

查看内置布局以了解如何定位功能。

创建功能

所有功能都必须实现 Box 接口。

任何功能的键方法是 render() 方法，该方法负责将功能渲染到图像上。此方法接收底层 Intervention\Image\Image 类的实例，允许您直接使用 Intervention 的修饰符，例如。

use Intervention\Image\Interfaces\ImageInterface;

public function render(ImageInterface $image)
{
  $image->drawCircle(10, 10, function ($circle) {
      $circle->radius(150);
      $circle->background('lightblue');
      $circle->border('b53717', 1);
  });
}

但是，您应该扩展 Box 类，因为这提供了一些有用的便利，尤其是如果您想使用相对定位的话。

测试

OG 使用 PHPUnit 和快照测试。

要运行集成测试，您需要安装所有 Composer 依赖项

composer install

您还需要 Node.js（版本 20 或更高）并安装 NPM 依赖项

npm install

完成这些操作后，您可以执行测试

./vendor/bin/phpunit

贡献

我非常欢迎任何有助于改进此包的 PR！

支持

所有支持均通过 GitHub 问题处理。

许可证

MIT 许可证（MIT）。有关详细信息，请参阅 LICENSE。

simonhamp / the-og

维护者

详细信息