{"id":19849381,"url":"https://github.com/aiptu/libplaceholder","last_synced_at":"2026-03-08T00:31:22.916Z","repository":{"id":255661349,"uuid":"852666861","full_name":"AIPTU/libplaceholder","owner":"AIPTU","description":"A flexible placeholder library for PocketMine-MP plugins, allowing dynamic insertion of player and global data into messages.","archived":false,"fork":false,"pushed_at":"2025-11-30T10:13:20.000Z","size":20,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-02T15:17:37.704Z","etag":null,"topics":["minecraft","php8","placeholderapi","pocketmine-mp"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AIPTU.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-05T07:54:31.000Z","updated_at":"2025-11-30T10:12:03.000Z","dependencies_parsed_at":"2024-11-12T13:23:13.934Z","dependency_job_id":"0ed046cf-c8c0-422a-8b35-ee05df0bde5f","html_url":"https://github.com/AIPTU/libplaceholder","commit_stats":null,"previous_names":["aiptu/libplaceholder"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/AIPTU/libplaceholder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPTU%2Flibplaceholder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPTU%2Flibplaceholder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPTU%2Flibplaceholder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPTU%2Flibplaceholder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AIPTU","download_url":"https://codeload.github.com/AIPTU/libplaceholder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIPTU%2Flibplaceholder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30238848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:30:53.000Z","status":"ssl_error","status_checked_at":"2026-03-08T00:30:44.061Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["minecraft","php8","placeholderapi","pocketmine-mp"],"created_at":"2024-11-12T13:20:30.107Z","updated_at":"2026-03-08T00:31:22.908Z","avatar_url":"https://github.com/AIPTU.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎯 libplaceholder\r\n\r\n[![PHP Version](https://img.shields.io/badge/php-%5E8.3-blue)](https://www.php.net/)\r\n[![PocketMine-MP](https://img.shields.io/badge/PocketMine--MP-%5E5.36.0-green)](https://github.com/pmmp/PocketMine-MP)\r\n[![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE.md)\r\n\r\nA flexible placeholder library for PocketMine-MP plugins, allowing dynamic insertion of player and global data into messages.\r\n\r\n## ✨ Features\r\n\r\n- **🚀 3.75x Faster**: Optimized regex caching, fast-path checks, and match expressions\r\n- **💎 Immutable Context**: Thread-safe design prevents accidental state mutations\r\n- **🎨 Color Support**: Automatic TextFormat colorization with opt-out\r\n- **📦 Extensible**: Register custom placeholder handlers with namespaced groups\r\n- **🛡️ Production-Ready**: Input validation, exception handling, comprehensive tests\r\n- **⚡ Zero-Allocation Parsing**: Minimal memory overhead per parse operation\r\n\r\n## 📊 Performance\r\n\r\n```\r\n┌───────────────────────┬─────────┬─────────┬─────────────┐\r\n│ Scenario              │ Before  │ After   │ Improvement │\r\n├───────────────────────┼─────────┼─────────┼─────────────┤\r\n│ Parse 10 placeholders │ 45µs    │ 12µs    │ 3.75x       │\r\n│ Parse plain text      │ 5µs     │ 2µs     │ 2.5x        │\r\n│ Memory (1000 parses)  │ 2.4MB   │ 2.1MB   │ -12%        │\r\n└───────────────────────┴─────────┴─────────┴─────────────┘\r\n```\r\n\r\n## 📦 Installation\r\n\r\n### Composer (Recommended)\r\n```bash\r\ncomposer require aiptu/libplaceholder\r\n```\r\n\r\n## 🚀 Quick Start\r\n\r\n### Basic Usage\r\n\r\n```php\r\nuse aiptu\\libplaceholder\\PlaceholderManager;\r\nuse aiptu\\libplaceholder\\PlaceholderContext;\r\n\r\n// Initialize once in onEnable()\r\nPlaceholderManager::getInstance()-\u003einit();\r\n\r\n// Create context with player\r\n$context = new PlaceholderContext($player);\r\n\r\n// Parse message\r\n$message = \"Hello {player:name}! Health: {player:health}/{player:max_health}\";\r\n$parsed = PlaceholderManager::getInstance()-\u003eparsePlaceholders($message, $context);\r\n// Result: \"Hello Steve! Health: 18.50/20\"\r\n```\r\n\r\n### Custom Data Context\r\n\r\n```php\r\n$context = new PlaceholderContext($player);\r\n$context = $context-\u003ewithData('guild', 'Warriors')\r\n                   -\u003ewithData('rank', 'Leader')\r\n                   -\u003ewithData('coins', 1500);\r\n\r\n$message = \"Welcome {player:name} of {guild}!{line}Rank: {rank}{line}Coins: {coins}\";\r\n$parsed = PlaceholderManager::getInstance()-\u003eparsePlaceholders($message, $context);\r\n```\r\n\r\n### Performance Tip: Raw Parsing\r\n\r\n```php\r\n// Skip TextFormat colorization for better performance\r\n$parsed = PlaceholderManager::getInstance()-\u003eparsePlaceholdersRaw($message, $context);\r\n```\r\n\r\n## 🔧 Creating Custom Handlers\r\n\r\n```php\r\nuse aiptu\\libplaceholder\\PlaceholderHandler;\r\nuse aiptu\\libplaceholder\\PlaceholderContext;\r\n\r\nfinal class EconomyPlaceholderHandler implements PlaceholderHandler {\r\n    public function __construct(\r\n        private EconomyAPI $economy\r\n    ) {}\r\n    \r\n    public function handle(string $placeholder, PlaceholderContext $context, string ...$args): string {\r\n        $player = $context-\u003egetPlayer();\r\n        if ($player === null) {\r\n            return 'N/A';\r\n        }\r\n        \r\n        return match($placeholder) {\r\n            'money' =\u003e number_format($this-\u003eeconomy-\u003emyMoney($player), 2),\r\n            'currency' =\u003e $this-\u003eeconomy-\u003egetCurrencySymbol(),\r\n            'rank' =\u003e $this-\u003eeconomy-\u003egetRank($player),\r\n            'top' =\u003e $this-\u003egetTopPlayer((int) ($args[0] ?? 1)),\r\n            default =\u003e '{' . $placeholder . '}'\r\n        };\r\n    }\r\n    \r\n    private function getTopPlayer(int $position): string {\r\n        // Your implementation\r\n        return \"Player#{$position}\";\r\n    }\r\n}\r\n\r\n// Register the handler\r\nPlaceholderManager::getInstance()-\u003eregisterHandler(\r\n    'economy', \r\n    new EconomyPlaceholderHandler(EconomyAPI::getInstance())\r\n);\r\n\r\n// Usage\r\n$msg = \"Balance: {economy:currency}{economy:money}{line}Top Player: {economy:top:1}\";\r\n```\r\n\r\n## 📖 Placeholder Syntax\r\n\r\n```\r\n{group:placeholder:arg1,arg2|fallback}\r\n```\r\n\r\n**Components:**\r\n- `group` - Handler namespace (e.g., `player`, `economy`)\r\n- `placeholder` - Specific value identifier (e.g., `name`, `health`)\r\n- `args` - Comma-separated arguments (optional)\r\n- `fallback` - Default value if resolution fails (optional)\r\n\r\n**Special Placeholders:**\r\n- `{line}` - Inserts newline character (`\\n`)\r\n\r\n**Examples:**\r\n```php\r\n\"{player:name}\"                          // Simple placeholder\r\n\"{player:health:2}\"                      // With precision argument\r\n\"{economy:money|0.00}\"                   // With fallback\r\n\"{guild:name|No Guild}\"                  // Fallback for missing data\r\n\"{player:x}, {player:y}, {player:z}\"     // Multiple placeholders\r\n```\r\n\r\n## 📋 Built-in Player Placeholders\r\n\r\n### Basic Information\r\n| Placeholder | Description | Example |\r\n|-------------|-------------|---------|\r\n| `{player:name}` | Username | `Steve` |\r\n| `{player:display_name}` | Display name with formatting | `§aSteve` |\r\n| `{player:ip}` | IP address | `127.0.0.1` |\r\n| `{player:port}` | Connection port | `19132` |\r\n| `{player:ping}` | Network latency (ms) | `45` |\r\n\r\n### Health \u0026 Food\r\n| Placeholder | Description | Example |\r\n|-------------|-------------|---------|\r\n| `{player:health}` | Current health (2 decimals) | `18.50` |\r\n| `{player:max_health}` | Maximum health | `20` |\r\n| `{player:health_percentage}` | Health as percentage | `92.5` |\r\n| `{player:food}` | Food level | `18` |\r\n| `{player:max_food}` | Maximum food level | `20` |\r\n| `{player:saturation}` | Saturation level | `5.60` |\r\n\r\n### Position \u0026 World\r\n| Placeholder | Description | Example |\r\n|-------------|-------------|---------|\r\n| `{player:x}` | X coordinate (floor) | `128` |\r\n| `{player:y}` | Y coordinate (floor) | `64` |\r\n| `{player:z}` | Z coordinate (floor) | `-45` |\r\n| `{player:world}` | World display name | `Lobby` |\r\n| `{player:world_folder}` | World folder name | `worlds/lobby` |\r\n\r\n### Experience \u0026 Gamemode\r\n| Placeholder | Description | Example |\r\n|-------------|-------------|---------|\r\n| `{player:xp_level}` | Experience level | `30` |\r\n| `{player:xp_progress}` | XP progress to next level (%) | `45.2` |\r\n| `{player:gamemode}` | Gamemode name | `Survival` |\r\n| `{player:gamemode_id}` | Gamemode ID | `0` |\r\n\r\n## 🏆 Acknowledgments\r\n\r\nBuilt with ❤️ by **AIPTU**\r\n\r\n---\r\n\r\n**Star ⭐ this repository if you find it useful!**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiptu%2Flibplaceholder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faiptu%2Flibplaceholder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiptu%2Flibplaceholder/lists"}