README

English Version

Laravel XML & JSON Helpers is a powerful, lightweight, and easy-to-use library for Laravel that helps you:

Convert arrays to XML with ease
Return XML responses in Laravel controllers
Generate standardized JSON API responses (success, errors, pagination, and more)
Work with XML and JSON seamlessly

Features

✅ Simple XML Conversion - Convert arrays to XML in one line ✅ Lightweight - Minimal dependencies, optimized for performance ✅ Easy Integration - Works seamlessly with Laravel 5.5+ ✅ Standardized API Responses - Build consistent JSON responses ✅ Pagination Support - Easy pagination for API resources ✅ Multiple HTTP Status Codes - Handle 200, 201, 204, 401, 403, 404, 500 and more ✅ Framework Auto-discovery - Automatic registration with Laravel 5.5+

Installation

Install the package via Composer:

composer require larataj/xml-helpers

Laravel will automatically register the service provider thanks to package auto-discovery. If you're using Laravel below 5.5, add it manually:

// config/app.php
'providers' => [
    Larataj\XmlHelpers\HelpersServiceProvider::class,
],

XML: Usage Guide

1. Convert Array to XML

use Larataj\XmlHelpers\ResponseHelper;

$array = [
    'name' => 'John Doe',
    'email' => 'john.doe@example.com',
    'roles' => ['admin', 'editor'],
];

$xml = ResponseHelper::arrayToXml($array);
echo $xml;

Output:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <name>John Doe</name>
  <email>john.doe@example.com</email>
  <roles>
    <item>admin</item>
    <item>editor</item>
  </roles>
</response>

2. Return XML Response in Laravel

use Larataj\XmlHelpers\ResponseHelper;

return ResponseHelper::xml([
    'status' => 'success',
    'message' => 'Data processed successfully',
    'data' => ['id' => 123, 'name' => 'John Doe'],
]);

3. Using the `response()->xml()` Macro

return response()->xml([
    'status' => 'success',
    'data' => ['id' => 123, 'name' => 'John Doe'],
]);

JSON API: Using `ApiResponse`

This library includes a convenient helper for generating standardized JSON responses.

use Larataj\XmlHelpers\Response\ApiResponse;

Success Response

return ApiResponse::success(['message' => 'OK']);

Created Response (201)

return ApiResponse::created($user);

Delete Resource

return ApiResponse::deleted();

Error Responses

return ApiResponse::error(['email' => 'Email is already taken']);
return ApiResponse::error('An error occurred');

Pagination

return ApiResponse::paginated($users, UserResource::class);

Ready-to-use HTTP Status Codes

ApiResponse::unauthorized(); // 401
ApiResponse::forbidden();    // 403
ApiResponse::notFound();     // 404
ApiResponse::serverError();  // 500
ApiResponse::noContent();    // 204

Example Routes for Testing

Route::get('/test-xml', function () {
    return response()->xml([
        'name' => 'Laravel',
        'version' => '10.x',
        'features' => ['fast', 'secure', 'elegant']
    ]);
});

Route::get('/test-json', function () {
    return \Larataj\XmlHelpers\Response\ApiResponse::success([
        'framework' => 'Laravel',
        'version' => app()->version(),
    ]);
});

Advanced Usage

Using XmlBuilder for Complex XML

The XmlBuilder class provides a fluent interface for building complex XML documents:

use Larataj\XmlHelpers\XmlBuilder;

$xml = new XmlBuilder('catalog', ['id' => '1']);

$xml->addChild('product', [
    'name' => 'Widget',
    'price' => '19.99',
    'stock' => '100'
])
->addChild('category', 'Electronics')
->addCData('description', 'A high-quality widget for your needs')
->addComment('Add more products as needed')
->addChild('tags', ['tag1' => 'new', 'tag2' => 'popular']);

echo $xml->toString(true); // true = formatted output

Parsing XML with XmlParser

Parse and query XML documents easily:

use Larataj\XmlHelpers\XmlParser;

// Parse XML string
$parser = new XmlParser('<root><item><name>Test</name></item></root>');

// Convert to array
$array = $parser->toArray();

// Query using XPath
$items = $parser->query('//item');

// Get single element
$firstItem = $parser->queryOne('//item[1]');

// Check if element exists
if ($parser->has('//item[@id="5"]')) {
    echo 'Item with id=5 found';
}

// Get pretty-printed XML
echo $parser->prettyPrint();

Using Response Macros

You can also use convenient response macros:

// Simple XML response
return response()->xml([
    'status' => 'success',
    'message' => 'Operation completed'
]);

// Using XML builder
$builder = response()->xmlBuilder('api-response', ['version' => '1.0']);
$builder->addChild('status', 'success')
        ->addChild('timestamp', now()->toIso8601String());

return response()->xml($builder->getXml()->asXML());

Requirements

PHP: 7.4, 8.0, 8.1, 8.2, 8.3, 8.4+
Laravel: 5.5, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0+

License

This package is licensed under the MIT License.

Author: Muhammad Vafoev

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Русская версия

Laravel XML & JSON Helpers

Установка

Установите пакет через Composer:

composer require larataj/xml-helpers

Laravel автоматически зарегистрирует провайдер благодаря автодетекту.
Если вы используете Laravel ниже 5.5, добавьте вручную:

// config/app.php
'providers' => [
    Larataj\XmlHelpers\HelpersServiceProvider::class,
],

XML: Использование

1. Преобразование массива в XML

use Larataj\XmlHelpers\ResponseHelper;

$array = [
    'name' => 'John Doe',
    'email' => 'john.doe@example.com',
    'roles' => ['admin', 'editor'],
];

$xml = ResponseHelper::arrayToXml($array);
echo $xml;

Результат:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <name>John Doe</name>
  <email>john.doe@example.com</email>
  <roles>
    <item>admin</item>
    <item>editor</item>
  </roles>
</response>

2. Возврат XML-ответа в Laravel

use Larataj\XmlHelpers\ResponseHelper;

return ResponseHelper::xml([
    'status' => 'success',
    'message' => 'Данные обработаны',
    'data' => ['id' => 123, 'name' => 'John Doe'],
]);

3. Использование макроса `response()->xml()`

return response()->xml([
    'status' => 'success',
    'data' => ['id' => 123, 'name' => 'John Doe'],
]);

JSON API: Использование `ApiResponse`

Библиотека включает удобный хелпер для формирования стандартизированных JSON-ответов.

use Larataj\XmlHelpers\Response\ApiResponse;

Успешный ответ

return ApiResponse::success(['message' => 'OK']);

Ответ `201 Created`

return ApiResponse::created($user);

Удаление ресурса

return ApiResponse::deleted();

Ошибки

return ApiResponse::error(['email' => 'Email уже занят']);
return ApiResponse::error('Произошла ошибка');

Пагинация

return ApiResponse::paginated($users, UserResource::class);

Готовые статусы:

ApiResponse::unauthorized(); // 401
ApiResponse::forbidden();    // 403
ApiResponse::notFound();     // 404
ApiResponse::serverError();  // 500
ApiResponse::noContent();    // 204

Пример маршрута для теста

Route::get('/test-xml', function () {
    return response()->xml([
        'name' => 'Laravel',
        'version' => '10.x',
        'features' => ['fast', 'secure', 'elegant']
    ]);
});

Route::get('/test-json', function () {
    return \Larataj\XmlHelpers\Response\ApiResponse::success([
        'framework' => 'Laravel',
        'version' => app()->version(),
    ]);
});

Расширенное использование

Использование XmlBuilder для сложного XML

Класс XmlBuilder предоставляет удобный интерфейс для построения сложных XML-документов:

use Larataj\XmlHelpers\XmlBuilder;

$xml = new XmlBuilder('каталог', ['id' => '1']);

$xml->addChild('товар', [
    'название' => 'Виджет',
    'цена' => '19.99',
    'количество' => '100'
])
->addChild('категория', 'Электроника')
->addCData('описание', 'Высокачественный виджет для ваших нужд')
->addComment('Добавьте больше товаров по необходимости')
->addChild('теги', ['тег1' => 'новое', 'тег2' => 'популярное']);

echo $xml->toString(true); // true = форматированный вывод

Парсинг XML с XmlParser

Легко парсьте и запрашивайте XML-документы:

use Larataj\XmlHelpers\XmlParser;

// Парсинг XML-строки
$parser = new XmlParser('<root><item><name>Тест</name></item></root>');

// Преобразование в массив
$array = $parser->toArray();

// Запрос с помощью XPath
$items = $parser->query('//item');

// Получение одного элемента
$firstItem = $parser->queryOne('//item[1]');

// Проверка существования элемента
if ($parser->has('//item[@id="5"]')) {
    echo 'Товар с id=5 найден';
}

// Красиво отформатированный XML
echo $parser->prettyPrint();

Использование макросов Response

Вы также можете использовать удобные макросы:

// Простой XML-ответ
return response()->xml([
    'status' => 'success',
    'message' => 'Операция выполнена'
]);

// Использование XML builder
$builder = response()->xmlBuilder('api-response', ['version' => '1.0']);
$builder->addChild('status', 'success')
        ->addChild('timestamp', now()->toIso8601String());

return response()->xml($builder->getXml()->asXML());

Требования

PHP: 7.4, 8.0, 8.1, 8.2, 8.3, 8.4+
Laravel: 5.5, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0+

Лицензия

Пакет распространяется под лицензией MIT.

Автор: Muhammad Vafoev

Содействие

Мы приветствуем вклад! Пожалуйста, ознакомьтесь с CONTRIBUTING.md для получения рекомендаций.

larataj / xml-helpers

Maintainers

Details