README

Пакет для Laravel, который рендерит schema-сущности JSON-LD через fluent API фасада. Поддерживает типы Person, Organization, Article, Product и WebSite, а также строгую валидацию и интеграцию с Blade.

Installation

composer require asmi046/laravel-jsonld

Configuration

Опубликуйте конфигурационный файл:

php artisan vendor:publish --tag=jsonld-config

Configuration Options

// config/jsonld.php
return [
    // Включить строгую валидацию (обязательные поля должны быть заполнены)
    'strict' => true,

    // Красивое форматирование JSON
    'pretty_print' => false,

    // Режим экранирования HTML: 'none', 'json_encode', 'htmlspecialchars'
    'escape_mode' => 'json_encode',

    // Флаги json_encode
    'json_flags' => JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
];

Usage

Fluent Builder API

use Asmi\JsonLd\Facades\JsonLd;

// Person
$person = JsonLd::person()
    ->name('John Doe')
    ->jobTitle('Software Developer')
    ->email('john@example.com')
    ->url('https://johndoe.com')
    ->render();

// Organization
$org = JsonLd::organization()
    ->name('Acme Corporation')
    ->url('https://acme.com')
    ->logo('https://acme.com/logo.png')
    ->email('contact@acme.com')
    ->telephone('+1-555-0100')
    ->render();

// Article
$article = JsonLd::article()
    ->headline('Understanding JSON-LD')
    ->description('Learn how to use JSON-LD for structured data...')
    ->datePublished('2026-04-09')
    ->dateModified('2026-04-10')
    ->image('https://example.com/image.jpg')
    ->author(JsonLd::person()->name('Jane Smith'))
    ->render();

// Product
$product = JsonLd::product()
    ->name('Awesome Product')
    ->description('The best product ever')
    ->price(99.99)
    ->priceCurrency('USD')
    ->image('https://example.com/product.jpg')
    ->brand(JsonLd::organization()->name('Brand Inc'))
    ->url('https://example.com/product')
    ->render();

// WebSite
$website = JsonLd::website()
    ->name('My Website')
    ->url('https://example.com')
    ->description('Welcome to my website')
    ->logo('https://example.com/logo.png')
    ->render();

Factory API

// Создание сущности через метод make
$person = JsonLd::make('Person', [
    'name' => 'John Doe',
    'jobTitle' => 'Developer',
    'email' => 'john@example.com',
])->render();

$org = JsonLd::make('Organization', [
    'name' => 'Acme Corp',
    'url' => 'https://acme.com',
])->render();

Using Helper Functions

// Fluent helper-функции
$person = jsonld_person()
    ->name('John Doe')
    ->jobTitle('Developer')
    ->render();

$org = jsonld_organization()->name('Acme Corp')->render();
$article = jsonld_article()->headline('My Post')->datePublished('2026-04-09')->render();
$product = jsonld_product()->name('Product')->price(99.99)->render();
$website = jsonld_website()->name('Site')->url('https://example.com')->render();

// Factory helper
$person = jsonld_make('Person', ['name' => 'John']);

In Blade Templates

<!-- Использование Blade-директивы -->
@jsonld($person)

<!-- Использование helper в выражении -->
{{ $article->render() }}

<!-- Построение inline -->
{{ JsonLd::person()->name('John')->render() }}

Getting Different Output Formats

$person = JsonLd::person()->name('John Doe');

// Рендер как HTML script tag (по умолчанию)
echo $person->render();

// Получить как JSON-строку
$json = $person->toJson();

// Получить как PHP-массив
$array = $person->toArray();

Entity Types

Person

Обязательные поля: name

Основные поля:

name - Полное имя
email - Email-адрес
jobTitle - Должность
url - URL сайта
image - URL изображения профиля
telephone - Телефон
description - Биография или описание
affiliation - Связанная организация
address - Физический адрес

Organization

Обязательные поля: name

Основные поля:

name - Название организации
url - URL сайта
logo - URL логотипа
description - Описание организации
email - Контактный email
telephone - Контактный телефон
address - Физический адрес
location - Информация о местоположении
sameAs - Массив ссылок на соцсети
contactPoint - Данные контактной точки

Article

Обязательные поля: headline, datePublished

Основные поля:

headline - Заголовок статьи
description - Описание/анонс статьи
image - URL главного изображения
author - Person или Organization (см. Person/Organization)
datePublished - Дата публикации (ISO 8601)
dateModified - Дата последнего изменения
url - URL статьи
articleBody - Полный текст статьи
keywords - Ключевые слова
publisher - Организация-издатель
articleSection - Раздел/категория статьи

Product

Обязательные поля: name

Основные поля:

name - Название товара
description - Описание товара
image - URL изображения товара
brand - Бренд (Organization)
price - Цена
priceCurrency - Код валюты (USD, EUR и т.д.)
url - URL товара
availability - Статус наличия
rating - Объект рейтинга
review - Объект отзыва
manufacturer - Производитель (Organization)
sku - Артикул товара

WebSite

Обязательные поля: name, url

Основные поля:

name - Название сайта
url - URL сайта
description - Описание сайта
image - Изображение сайта
logo - URL логотипа
language - Код языка
potentialAction - Действия (например SearchAction)
copyrightHolder - Правообладатель
author - Автор сайта

Validation

Пакет проверяет обязательные поля в строгом режиме (включен по умолчанию). При ошибках валидации выбрасывается ValidationException с детализацией по полям:

use Asmi\JsonLd\Exceptions\ValidationException;

try {
    $person = JsonLd::person()->render(); // Отсутствует обязательное поле 'name'
} catch (ValidationException $e) {
    $errors = $e->getErrors();
    // ['name' => "Required field 'name' is missing."]
}

Отключить строгую валидацию:

// In config/jsonld.php
'strict' => false,

// Или временно
config(['jsonld.strict' => false]);
$person = JsonLd::person()->render(); // Исключение выброшено не будет

Пример вывода

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Person",
    "name": "John Doe",
    "jobTitle": "Developer",
    "email": "john@example.com"
  }
</script>

С включенным pretty_print:

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Person",
    "name": "John Doe",
    "jobTitle": "Developer",
    "email": "john@example.com"
  }
</script>

Testing

php vendor/bin/phpunit

# С coverage
php vendor/bin/phpunit --coverage-html coverage

Contributing

Подробности смотрите в CONTRIBUTING.md.

License

Лицензия MIT. Подробности в LICENSE.

asmi046 / laravel-jsonld

Maintainers

Package info

Statistics

Security

README

Installation

Configuration

Configuration Options

Usage

Fluent Builder API

Factory API

Using Helper Functions

In Blade Templates

Getting Different Output Formats

Entity Types

Person

Organization

Article

Product

WebSite

Validation

Пример вывода

Testing

Contributing

License