README

A lightweight, modern JSON library for PHP with clean API and excellent error handling.

A lightweight, elegant JSON handling library for PHP with clean API, excellent error handling, and zero dependencies.

✨ Features

🚀 Clean API - Simple static methods
🛡️ Exception-based error handling - No silent failures
📁 File operations - Read/write JSON files
✅ Validation - Check if strings are valid JSON
🎨 Formatting - Pretty printing & minification
🔄 Merging - Deep merge capabilities
🪶 Zero dependencies - Pure PHP
💯 100% compatible with PHP 7.4+

📦 Installation

Using Composer

composer require almhdy/jsonella

Manual Installation

Download and include the library:

require_once 'src/JSON.php';

🚀 Quick Start

<?php
require_once 'vendor/autoload.php';

use Almhdy24\jsonella\JSON;

// Encode data to JSON
$data = ['name' => 'John', 'age' => 30, 'skills' => ['PHP', 'JSON']];
$json = JSON::encode($data);

// Decode JSON string
$array = JSON::decode($json);

// Pretty print for debugging
echo JSON::pretty($data);

// Read JSON from file
$config = JSON::readFile('config.json');

// Write JSON to file
JSON::writeFile('data.json', $data, true);

📚 Usage Examples

Basic Encoding/Decoding

// Encode with pretty print
$prettyJson = JSON::encode($data, true);

// Decode as object
$object = JSON::decode($json, false);

// Check if valid JSON
if (JSON::isValid($jsonString)) {
    // Process JSON
}

File Operations

// Read and write files
$users = JSON::readFile('users.json');
$users[] = ['name' => 'New User'];
JSON::writeFile('users.json', $users, true);

Advanced Features

// Merge multiple JSON arrays
$json1 = '{"a": 1, "b": 2}';
$json2 = '{"b": 3, "c": 4}';
$merged = JSON::merge([$json1, $json2], true);

// Minify JSON
$minified = JSON::minify($prettyJson);

// Flatten array
$flat = JSON::flatten(['user' => ['name' => 'John', 'age' => 30]]);
// Result: ['user.name' => 'John', 'user.age' => 30]

Error Handling

try {
    $data = JSON::decode('{invalid json}');
} catch (InvalidArgumentException $e) {
    echo 'Error: ' . $e->getMessage();
}

try {
    JSON::writeFile('/invalid/path/data.json', $data);
} catch (RuntimeException $e) {
    echo 'File error: ' . $e->getMessage();
}

📋 API Reference

Static Methods

Method	Description
`JSON::encode($data, $pretty = false)`	Encode data to JSON
`JSON::decode($json, $assoc = true)`	Decode JSON string
`JSON::isValid($string)`	Validate JSON string
`JSON::readFile($filepath, $assoc = true)`	Read JSON from file
`JSON::writeFile($filepath, $data, $pretty = false)`	Write JSON to file
`JSON::pretty($data)`	Pretty print data
`JSON::minify($json)`	Minify JSON string
`JSON::merge($jsonItems, $mergeArrays = false)`	Merge JSON data
`JSON::lastError()`	Get last JSON error
`JSON::toArray($data)`	Convert object to array
`JSON::flatten($array, $prefix = '')`	Flatten array with dot notation

🧪 Testing

Run the test suite:

composer test
# or
php tests/JSONTest.php

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Thanks to all contributors
Inspired by the need for better JSON handling in PHP
Built with ❤️ by almhdy24

Made with ❤️ by almhdy24

almhdy24 / jsonella

Maintainers

Details