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

🧪 Testing

Run the test suite:

composer test
# or
php tests/JSONTest.php

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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