README

Пакет для Laravel, который рендерит schema-сущности JSON-LD через fluent API фасада. Поддерживает типы Person, Organization, Article, Product, WebSite, LocalBusiness, TravelAgency и TouristTrip, а также строгую валидацию и интеграцию с 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();

// LocalBusiness
$localBusiness = JsonLd::localBusiness()
    ->name('Кофейня на Арбате')
    ->url('https://coffeeshop.ru')
    ->telephone('+7-495-000-0000')
    ->address('Арбат, 10, Москва')
    ->openingHours('Mo-Fr 08:00-22:00')
    ->priceRange('$$')
    ->geo(['@type' => 'GeoCoordinates', 'latitude' => 55.7522, 'longitude' => 37.5722])
    ->paymentAccepted(['Cash', 'Credit Card'])
    ->render();

// TravelAgency
$travelAgency = JsonLd::travelAgency()
    ->name('Путешествия мечты')
    ->url('https://dream-travel.ru')
    ->telephone('+7-800-000-0000')
    ->email('info@dream-travel.ru')
    ->openingHours('Mo-Su 09:00-21:00')
    ->areaServed(['Россия', 'Европа', 'Азия'])
    ->serviceType('Туристические туры')
    ->render();

// TouristTrip
$trip = JsonLd::touristTrip()
    ->name('Золотое кольцо на выходные')
    ->description('Культурный тур по древним городам России')
    ->startDate('2026-06-01')
    ->endDate('2026-06-03')
    ->touristType(['Семьи', 'Пары'])
    ->itinerary(['Москва', 'Сергиев Посад', 'Суздаль'])
    ->provider(JsonLd::travelAgency()->name('Путешествия мечты'))
    ->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();

$localBusiness = JsonLd::make('LocalBusiness', [
    'name' => 'Кофейня на Арбате',
    'telephone' => '+7-495-000-0000',
    'openingHours' => 'Mo-Fr 08:00-22:00',
])->render();

$travelAgency = JsonLd::make('TravelAgency', [
    'name' => 'Путешествия мечты',
    'areaServed' => ['Россия', 'Европа'],
    'serviceType' => 'Туристические туры',
])->render();

$trip = JsonLd::make('TouristTrip', [
    'name' => 'Золотое кольцо на выходные',
    'startDate' => '2026-06-01',
    'endDate' => '2026-06-03',
    'touristType' => ['Семьи', 'Пары'],
])->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();
$localBusiness = jsonld_local_business()->name('Кофейня')->openingHours('Mo-Fr 08:00-22:00')->render();
$travelAgency = jsonld_travel_agency()->name('Агентство')->areaServed('Россия')->render();
$trip = jsonld_tourist_trip()->name('Тур')->startDate('2026-06-01')->render();

// Factory helper
$person = jsonld_make('Person', ['name' => 'John']);
$localBusiness = jsonld_make('LocalBusiness', ['name' => 'Кофейня']);
$travelAgency = jsonld_make('TravelAgency', ['name' => 'Агентство']);
$trip = jsonld_make('TouristTrip', ['name' => 'Тур']);

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 - Автор сайта

LocalBusiness

Наследует все поля Organization. Представляет физическое местное заведение.

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

Основные поля (унаследованы от Organization):

name - Название заведения
url - URL сайта
telephone - Телефон
email - Email
address - Физический адрес
logo - URL логотипа
description - Описание
sameAs - Ссылки на соцсети

Специфичные поля:

openingHours - Часы работы (например Mo-Fr 08:00-22:00)
priceRange - Ценовой диапазон ($, $$, $$$ и т.д.)
geo - Географические координаты (@type: GeoCoordinates, latitude, longitude)
paymentAccepted - Принимаемые способы оплаты (строка или массив)

TravelAgency

Наследует все поля LocalBusiness. Представляет туристическое агентство.

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

Специфичные поля:

areaServed - Обслуживаемые регионы (строка или массив)
serviceType - Тип туристических услуг

TouristTrip

Представляет туристическую поездку/тур.

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

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

name - Название тура
description - Описание тура
startDate - Дата начала (ISO 8601)
endDate - Дата окончания (ISO 8601)
itinerary - Маршрут или программа тура (строка или массив)
offers - Коммерческое предложение (например Offer)
touristType - Целевая аудитория туристов (строка или массив)
provider - Организатор тура (Organization, TravelAgency или массив)

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

LocalBusiness

TravelAgency

TouristTrip

Validation

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

Testing

Contributing

License