{"id":34639887,"url":"https://github.com/projectsaturnstudios/pocketflow-php","last_synced_at":"2025-12-24T17:15:45.709Z","repository":{"id":301549048,"uuid":"1009600316","full_name":"projectsaturnstudios/pocketflow-php","owner":"projectsaturnstudios","description":"A translation of The-Pocket/pocketflow for PHP","archived":false,"fork":false,"pushed_at":"2025-07-03T00:33:16.000Z","size":15,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T11:05:02.843Z","etag":null,"topics":["agent","agentic-ai","agentic-framework","agents","ai-framework","ai-frameworks","artificial-intelligence","automations","flow-based-programming","flow-engineering","laravel","large-language-model","large-language-models","llm","llm-agent","php","pocket-flow","workflow","workflow-orchestration"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/projectsaturnstudios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-06-27T11:53:10.000Z","updated_at":"2025-08-10T16:32:36.000Z","dependencies_parsed_at":"2025-06-27T13:05:50.747Z","dependency_job_id":"0476af46-f4c9-4fed-a4ce-db7a3e44779f","html_url":"https://github.com/projectsaturnstudios/pocketflow-php","commit_stats":null,"previous_names":["projectsaturnstudios/pocketflow-php"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/projectsaturnstudios/pocketflow-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fpocketflow-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fpocketflow-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fpocketflow-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fpocketflow-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/projectsaturnstudios","download_url":"https://codeload.github.com/projectsaturnstudios/pocketflow-php/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectsaturnstudios%2Fpocketflow-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28005414,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agent","agentic-ai","agentic-framework","agents","ai-framework","ai-frameworks","artificial-intelligence","automations","flow-based-programming","flow-engineering","laravel","large-language-model","large-language-models","llm","llm-agent","php","pocket-flow","workflow","workflow-orchestration"],"created_at":"2025-12-24T17:15:43.254Z","updated_at":"2025-12-24T17:15:45.703Z","avatar_url":"https://github.com/projectsaturnstudios.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PocketFlow PHP\n\n\u003e PocketFlow PHP: Minimalist LLM framework for PHP. Let Agents build Agents!\n\n**Language:** PHP | **License:** MIT\n\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![PHP](https://img.shields.io/badge/PHP-8.1%2B-blue.svg)\n![ReactPHP](https://img.shields.io/badge/ReactPHP-Optional-orange.svg)\n[![Total Downloads](http://poser.pugx.org/projectsaturnstudios/pocketflow-php/downloads)](https://packagist.org/packages/pocketflow-php/downloads)\n\nPocketFlow PHP is the **first PHP implementation** of the [minimalist LLM framework](https://github.com/The-Pocket/PocketFlow) concept\n\n- **Lightweight**: ~400 lines of PHP. Zero bloat, pure PHP elegance.\n  \n- **Framework Agnostic**: Works with any PHP project, not tied to specific frameworks.\n\n- **Graph-Based**: Simple node and flow abstraction for complex LLM workflows.\n\n- **ReactPHP Ready**: Optional async support for parallel processing.\n\nGet started with PocketFlow PHP:\n- **Installation**: `composer require projectsaturnstudios/pocketflow-php`\n- **Quick Start**: Copy the [source files](https://github.com/projectsaturnstudios/pocketflow-php/tree/main/src) into your PHP project\n- **Documentation**: Examples in this README and source code\n- **LLM Integration**: Bring your own LLM client (OpenAI SDK, Guzzle, etc.)\n\n## Why PocketFlow PHP?\n\nThe PHP ecosystem was missing a minimalist LLM workflow framework... until now!\n\n\u003cdiv align=\"center\"\u003e\n\n|                | **Abstraction**          | **PHP Integration**                                      | **LLM Support**                                    | **Lines**       | **Dependencies**    |\n|----------------|:-----------------------------: |:-----------------------------------------------------------:|:------------------------------------------------------------:|:---------------:|:----------------------------:|\n| LLPhant  | Comprehensive               | Framework agnostic \u003cbr\u003e\u003csup\u003e\u003csub\u003e(Symfony/Laravel compatible)\u003c/sub\u003e\u003c/sup\u003e              | Multiple providers \u003cbr\u003e\u003csup\u003e\u003csub\u003e(OpenAI, Anthropic, Mistral, etc.)\u003c/sub\u003e\u003c/sup\u003e                   | ~15K+          | Heavy (many providers)                     |\n| LangChain PHP   | Agent, Chain                | Basic \u003cbr\u003e\u003csup\u003e\u003csub\u003e(Work in progress)\u003c/sub\u003e\u003c/sup\u003e         | Limited \u003cbr\u003e\u003csup\u003e\u003csub\u003e(OpenAI, llama.cpp)\u003c/sub\u003e\u003c/sup\u003e        | ~5K           | Moderate                     |\n| **PocketFlow PHP** | **Graph**                    | **Framework Agnostic** \u003cbr\u003e\u003csup\u003e\u003csub\u003e(Pure PHP, works anywhere)\u003c/sub\u003e\u003c/sup\u003e                                                 | **Bring Your Own** \u003cbr\u003e\u003csup\u003e\u003csub\u003e(Use any HTTP client)\u003c/sub\u003e\u003c/sup\u003e                                                  | **~400**       | **Minimal**                  |\n\n\u003c/div\u003e\n\n## How does PocketFlow PHP work?\n\nThe core abstraction: **Graph-based workflow execution** with simple nodes and flows.\n\n### Core Components:\n\n1. **BaseNode**: Foundation class with `prep()`, `exec()`, `post()` lifecycle\n2. **Node**: Extended with retry logic and fallback handling  \n3. **Flow**: Orchestrates node execution with action-based routing\n4. **BatchNode/BatchFlow**: Process arrays of data through workflows\n5. **AsyncNode/AsyncFlow**: ReactPHP-powered parallel execution (optional)\n\n### Key Features:\n\n- **Reference Passing**: Proper `\u0026$shared` parameter handling for state persistence\n- **Type Safety**: Full PHP 8.1+ type declarations\n- **Error Handling**: Comprehensive exception handling with fallbacks\n- **Memory Management**: Configurable data retention\n\n## Examples\n\n### Basic Hello World\n```php\n\u003c?php\nrequire 'vendor/autoload.php';\n\nuse ProjectSaturnStudios\\PocketFlowPHP\\{Node, Flow};\n\nclass HelloNode extends Node \n{\n    public function exec(mixed $prep_res): mixed \n    {\n        return \"Hello, \" . ($prep_res['name'] ?? 'World') . \"!\";\n    }\n}\n\nclass OutputNode extends Node \n{\n    public function prep(mixed \u0026$shared): mixed \n    {\n        return $shared; // Pass through shared data\n    }\n    \n    public function exec(mixed $prep_res): mixed \n    {\n        echo $prep_res['greeting'] ?? 'No greeting found';\n        return 'done';\n    }\n    \n    public function post(mixed \u0026$shared, mixed $prep_res, mixed $exec_res): mixed \n    {\n        return $exec_res;\n    }\n}\n\n// Create nodes\n$helloNode = new HelloNode();\n$outputNode = new OutputNode();\n\n// Chain them\n$helloNode-\u003enext($outputNode, 'success');\n\n// Create flow and run\n$flow = new Flow($helloNode);\n$shared = ['name' =\u003e 'PocketFlow'];\n\n$result = $flow-\u003e_run($shared);\n```\n\n### LLM Integration Example\n```php\n\u003c?php\n// Bring your own LLM client\nuse OpenAI\\Client as OpenAIClient;\n\nclass LLMNode extends Node \n{\n    public function __construct(private OpenAIClient $client) {}\n    \n    public function prep(mixed \u0026$shared): mixed \n    {\n        return ['prompt' =\u003e $shared['prompt'] ?? 'Say hello!'];\n    }\n    \n    public function exec(mixed $prep_res): mixed \n    {\n        $response = $this-\u003eclient-\u003echat()-\u003ecreate([\n            'model' =\u003e 'gpt-3.5-turbo',\n            'messages' =\u003e [\n                ['role' =\u003e 'user', 'content' =\u003e $prep_res['prompt']]\n            ]\n        ]);\n        \n        return $response-\u003echoices[0]-\u003emessage-\u003econtent;\n    }\n    \n    public function post(mixed \u0026$shared, mixed $prep_res, mixed $exec_res): mixed \n    {\n        $shared['llm_response'] = $exec_res;\n        return 'success';\n    }\n}\n\n// Usage\n$client = OpenAI::client('your-api-key');\n$llmNode = new LLMNode($client);\n$outputNode = new OutputNode();\n\n$llmNode-\u003enext($outputNode, 'success');\n$flow = new Flow($llmNode);\n\n$shared = ['prompt' =\u003e 'Write a haiku about PHP'];\n$flow-\u003e_run($shared);\n```\n\n### Self-Looping Chat Bot\n```php\n\u003c?php\nclass ChatNode extends Node \n{\n    public function __construct(private $llmClient) {}\n    \n    public function prep(mixed \u0026$shared): mixed \n    {\n        // Get user input\n        echo \"You: \";\n        $input = trim(fgets(STDIN));\n        \n        if ($input === 'exit') {\n            return ['action' =\u003e 'exit'];\n        }\n        \n        $shared['messages'][] = ['role' =\u003e 'user', 'content' =\u003e $input];\n        return ['messages' =\u003e $shared['messages']];\n    }\n    \n    public function exec(mixed $prep_res): mixed \n    {\n        if ($prep_res['action'] === 'exit') {\n            return 'exit';\n        }\n        \n        // Call your LLM here\n        $response = $this-\u003ellmClient-\u003echat($prep_res['messages']);\n        return $response;\n    }\n    \n    public function post(mixed \u0026$shared, mixed $prep_res, mixed $exec_res): mixed \n    {\n        if ($exec_res === 'exit') {\n            echo \"Goodbye!\\n\";\n            return 'exit';\n        }\n        \n        echo \"AI: $exec_res\\n\\n\";\n        $shared['messages'][] = ['role' =\u003e 'assistant', 'content' =\u003e $exec_res];\n        \n        return 'continue'; // Self-loop\n    }\n}\n\n// Create self-looping chat\n$chatNode = new ChatNode($yourLLMClient);\n$chatNode-\u003enext($chatNode, 'continue'); // Self-loop!\n\n$flow = new Flow($chatNode);\n$shared = ['messages' =\u003e []];\n$flow-\u003e_run($shared);\n```\n\n## Advanced Patterns\n\n### Batch Processing\n```php\n$batchNode = new BatchNode();\n$batchNode-\u003esetItems(['item1', 'item2', 'item3']);\n$batchFlow = new BatchFlow($batchNode);\n```\n\n### Async Workflows (ReactPHP - Optional Dependency)\n```php\n// composer require react/socket\nuse React\\EventLoop\\Loop;\n\n$asyncNode = new AsyncNode();\n$asyncFlow = new AsyncFlow($asyncNode);\n// Parallel execution with promises\n```\n\n### Conditional Routing\n```php\n$nodeA-\u003enext($nodeB, 'success');\n$nodeA-\u003enext($nodeC, 'error'); \n$nodeA-\u003enext($nodeD, 'retry');\n```\n\n## Comparison with Original PocketFlow\n\n| Feature | Python PocketFlow | PHP PocketFlow | Notes |\n|---------|------------------|----------------|-------|\n| Core Abstraction | ✅ Graph | ✅ Graph | Same philosophy |\n| Async Support | ✅ asyncio | ⚠️ ReactPHP (optional) | Different implementations |\n| Framework Integration | ❌ None | ✅ Framework Agnostic | Works with any PHP project |\n| LLM Providers | ❌ Manual | ❌ Bring Your Own | Both require manual integration |\n| Type Safety | ⚠️ Optional | ✅ Full | PHP 8.1+ strict types |\n| Lines of Code | 100 | ~400 | More features, still minimal |\n\n## Installation \u0026 Setup\n\n### Requirements\n- PHP 8.1+\n- Composer\n\n### Installation\n```bash\ncomposer require projectsaturnstudios/pocketflow-php\n```\n\n### Optional Dependencies\n```bash\n# For async support\ncomposer require react/socket\n\n# For LLM integration (examples)\ncomposer require openai-php/client\ncomposer require guzzlehttp/guzzle\n```\n\n### Quick Setup\n1. **Install Package**: `composer require projectsaturnstudios/pocketflow-php`\n2. **Create Nodes**: Extend `Node` or `BaseNode` classes\n3. **Chain Workflows**: Use `$node-\u003enext($nextNode, 'action')`\n4. **Run Flows**: `$flow = new Flow($startNode); $flow-\u003e_run($shared);`\n\n## LLM Integration Notes\n\n**Important**: PocketFlow PHP is **framework-agnostic** and does **not** include LLM provider integrations. You need to:\n\n1. **Choose Your LLM Client**: OpenAI SDK, Guzzle HTTP, cURL, etc.\n2. **Implement in Nodes**: Add LLM calls in your `exec()` methods\n3. **Handle Responses**: Process LLM responses in your `post()` methods\n4. **Manage State**: Use `\u0026$shared` parameters for conversation history\n\nThis approach gives you **complete control** over your LLM integrations without vendor lock-in.\n\n## Vendor Dependencies\n\n**Dependencies:**\n- **ReactPHP**: Required only for async features (optional)\n- **PHP 8.1+**: Required for type safety and modern features\n\n**No Lock-ins:**\n- ❌ No specific LLM provider\n- ❌ No specific HTTP client  \n- ❌ No specific framework\n- ❌ No specific database\n\n## Contributing\n\nThis is the **world's first PHP implementation** of PocketFlow! We welcome contributions:\n\n- 🐛 **Bug Reports**: Found an issue? Let us know!\n- 🚀 **Feature Requests**: Ideas for PHP-specific features?\n- 📖 **Documentation**: Help improve our docs\n- 🧪 **Examples**: Share your PocketFlow PHP workflows\n\n## Roadmap\n\n- [x] **Core Framework**: Basic node and flow implementation\n- [x] **Async Support**: ReactPHP integration\n- [x] **Batch Processing**: Array and parallel processing\n- [ ] **More Examples**: Real-world workflow patterns\n- [ ] **Performance**: Optimize for large-scale applications  \n- [ ] **Testing**: Comprehensive test suite\n- [ ] **Documentation**: Full API documentation\n\n## License\n\nMIT License - same as original PocketFlow\n\n## Acknowledgments\n\n- **Original PocketFlow**: [The-Pocket/PocketFlow](https://github.com/The-Pocket/PocketFlow) - The inspiration and foundation\n- **ReactPHP**: For async capabilities in PHP (optional dependency)\n- **PHP Community**: For the amazing language ecosystem\n\n---\n\nBuilt with ADHD by Project Saturn Studios \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectsaturnstudios%2Fpocketflow-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojectsaturnstudios%2Fpocketflow-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectsaturnstudios%2Fpocketflow-php/lists"}