{"id":15307994,"url":"https://github.com/n1crack/subset-finder","last_synced_at":"2026-02-09T04:07:54.249Z","repository":{"id":221113305,"uuid":"753483220","full_name":"n1crack/subset-finder","owner":"n1crack","description":"A Laravel collection-powered PHP package, enables efficient extraction of subsets from collections, ideal for discount calculations and inventory management.","archived":false,"fork":false,"pushed_at":"2026-01-12T18:10:50.000Z","size":106,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-12T23:52:47.826Z","etag":null,"topics":["collection","discount","ecommerce","php","subset-selection"],"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/n1crack.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"n1crack","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2024-02-06T08:02:16.000Z","updated_at":"2026-01-12T18:10:47.000Z","dependencies_parsed_at":"2024-02-06T08:53:08.283Z","dependency_job_id":"d90121b7-5c40-4c97-ac94-b92ff9dbd87c","html_url":"https://github.com/n1crack/subset-finder","commit_stats":null,"previous_names":["n1crack/subset-finder"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/n1crack/subset-finder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n1crack%2Fsubset-finder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n1crack%2Fsubset-finder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n1crack%2Fsubset-finder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n1crack%2Fsubset-finder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n1crack","download_url":"https://codeload.github.com/n1crack/subset-finder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n1crack%2Fsubset-finder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29256065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T03:07:45.136Z","status":"ssl_error","status_checked_at":"2026-02-09T03:07:24.123Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["collection","discount","ecommerce","php","subset-selection"],"created_at":"2024-10-01T08:13:15.633Z","updated_at":"2026-02-09T04:07:54.243Z","avatar_url":"https://github.com/n1crack.png","language":"PHP","funding_links":["https://github.com/sponsors/n1crack"],"categories":[],"sub_categories":[],"readme":"# SubsetFinder PHP Package\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/ozdemir/subset-finder)](https://packagist.org/packages/ozdemir/subset-finder)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/n1crack/subset-finder/run-tests.yml)](https://github.com/n1crack/subset-finder/actions)\n[![GitHub](https://github.com/n1crack/subset-finder/blob/main/LICENSE.md)](https://github.com/n1crack/subset-finder/blob/main/LICENSE.md)\n\nA powerful and flexible PHP package for efficiently finding subsets within collections based on quantity criteria. Built with Laravel collections and optimized for performance, memory efficiency, and developer experience.\n\n## Features\n\n- **High Performance**: Optimized algorithms with configurable memory limits\n- **Flexible Configuration**: Multiple configuration profiles for different use cases\n- **Performance Monitoring**: Built-in metrics and logging capabilities\n- **Robust Error Handling**: Comprehensive validation and meaningful error messages\n- **Type Safety**: Full PHP 8.1+ type support with strict validation\n- **Comprehensive Testing**: 100% test coverage with Pest PHP\n- **Laravel Integration**: Service provider, facade, and trait support\n- **Memory Efficient**: Optional lazy evaluation for large datasets\n\n## Installation\n\n```bash\ncomposer require ozdemir/subset-finder\n```\n\n### Laravel Integration\n\nThe package automatically registers with Laravel. If you need to publish the configuration:\n\n```bash\nphp artisan vendor:publish --tag=subset-finder-config\n```\n\n## Quick Start\n\n### Basic Usage\n\n```php\nuse Ozdemir\\SubsetFinder\\Subset;\nuse Ozdemir\\SubsetFinder\\SubsetCollection;\nuse Ozdemir\\SubsetFinder\\SubsetFinder;\nuse Ozdemir\\SubsetFinder\\SubsetFinderConfig;\n\n// Define your collection and subset criteria\n$collection = collect([\n    new Product(id: 1, quantity: 11, price: 15),\n    new Product(id: 2, quantity: 6, price: 5),\n    new Product(id: 3, quantity: 6, price: 5),\n]);\n\n$subsetCollection = new SubsetCollection([\n    Subset::of([1, 2])-\u003etake(5),  // Find 5 items from products 1 and 2\n    Subset::of([3])-\u003etake(2),      // Find 2 items from product 3\n]);\n\n// Create and configure SubsetFinder\n$config = new SubsetFinderConfig(\n    idField: 'id',\n    quantityField: 'quantity',\n    sortField: 'price',        // Sort by price (ascending)\n    sortDescending: false\n);\n\n$subsetFinder = new SubsetFinder($collection, $subsetCollection, $config);\n$subsetFinder-\u003esolve();\n\n// Get results\n$foundSubsets = $subsetFinder-\u003egetFoundSubsets();\n$remaining = $subsetFinder-\u003egetRemaining();\n$maxSubsets = $subsetFinder-\u003egetSubsetQuantity();\n```\n\n### Using Configuration Profiles\n\n```php\n// For large datasets (512MB memory, lazy evaluation enabled)\n$subsetFinder = new SubsetFinder(\n    $collection, \n    $subsetCollection, \n    SubsetFinderConfig::forLargeDatasets()\n);\n\n// For performance (64MB memory, lazy evaluation disabled)\n$subsetFinder = new SubsetFinder(\n    $collection, \n    $subsetCollection, \n    SubsetFinderConfig::forPerformance()\n);\n\n// For balanced approach (256MB memory, lazy evaluation enabled)\n$subsetFinder = new SubsetFinder(\n    $collection, \n    $subsetCollection, \n    SubsetFinderConfig::forBalanced()\n);\n```\n\n### Using the Facade\n\n```php\nuse Ozdemir\\SubsetFinder\\Facades\\SubsetFinder;\n\n// Create with default configuration\n$subsetFinder = SubsetFinder::create($collection, $subsetCollection);\n\n// Create with specific profile\n$subsetFinder = SubsetFinder::forLargeDatasets($collection, $subsetCollection);\n$subsetFinder = SubsetFinder::forPerformance($collection, $subsetCollection);\n```\n\n### Using the Trait\n\n```php\nuse Ozdemir\\SubsetFinder\\Traits\\HasSubsetOperations;\n\nclass ProductCollection extends Collection\n{\n    use HasSubsetOperations;\n}\n\n$products = new ProductCollection([...]);\n\n// Find subsets directly on the collection\n$subsetFinder = $products-\u003efindSubsets($subsetCollection);\n\n// Use profiles\n$subsetFinder = $products-\u003efindSubsetsWithProfile($subsetCollection, 'large_datasets');\n\n// Check feasibility\nif ($products-\u003ecanSatisfySubsets($subsetCollection)) {\n    // Proceed with subset creation\n}\n```\n\n## Use Cases\n\n### E-commerce Bundle Creation\n```php\n$products = collect([\n    new Product(id: 1, quantity: 100, price: 10),  // T-shirt\n    new Product(id: 2, quantity: 50, price: 5),    // Socks\n    new Product(id: 3, quantity: 25, price: 20),   // Hat\n]);\n\n$bundles = new SubsetCollection([\n    Subset::of([1, 2])-\u003etake(2),  // T-shirt + Socks bundle\n    Subset::of([1, 3])-\u003etake(1),  // T-shirt + Hat bundle\n]);\n\n$subsetFinder = new SubsetFinder($products, $bundles);\n$subsetFinder-\u003esolve();\n\n// Create 25 T-shirt + Socks bundles\n// Create 25 T-shirt + Hat bundles\n// Remaining: 25 T-shirts, 0 socks, 0 hats\n```\n\n### Inventory Management\n```php\n$inventory = collect([\n    new Item(id: 'A', quantity: 100, category: 'electronics'),\n    new Item(id: 'B', quantity: 200, category: 'clothing'),\n    new Item(id: 'C', quantity: 150, category: 'books'),\n]);\n\n$orders = new SubsetCollection([\n    Subset::of(['A', 'B'])-\u003etake(10),  // Electronics + Clothing order\n    Subset::of(['C'])-\u003etake(5),        // Books order\n]);\n\n$subsetFinder = new SubsetFinder($inventory, $orders);\n$subsetFinder-\u003esolve();\n```\n\n## Configuration\n\n### Environment Variables\n\n```env\nSUBSET_FINDER_MAX_MEMORY=256M\nSUBSET_FINDER_LAZY_EVALUATION=true\nSUBSET_FINDER_LOGGING=true\nSUBSET_FINDER_LOG_CHANNEL=subset-finder\nSUBSET_FINDER_LOG_LEVEL=info\n```\n\n### Configuration File\n\n```php\n// config/subset-finder.php\nreturn [\n    'defaults' =\u003e [\n        'id_field' =\u003e 'id',\n        'quantity_field' =\u003e 'quantity',\n        'sort_field' =\u003e 'id',\n        'sort_descending' =\u003e false,\n        'max_memory_usage' =\u003e env('SUBSET_FINDER_MAX_MEMORY', 128 * 1024 * 1024),\n        'enable_lazy_evaluation' =\u003e env('SUBSET_FINDER_LAZY_EVALUATION', true),\n        'enable_logging' =\u003e env('SUBSET_FINDER_LOGGING', false),\n    ],\n    \n    'profiles' =\u003e [\n        'large_datasets' =\u003e [\n            'max_memory_usage' =\u003e 512 * 1024 * 1024,\n            'enable_lazy_evaluation' =\u003e true,\n            'enable_logging' =\u003e true,\n        ],\n        'performance' =\u003e [\n            'max_memory_usage' =\u003e 64 * 1024 * 1024,\n            'enable_lazy_evaluation' =\u003e false,\n            'enable_logging' =\u003e false,\n        ],\n    ],\n];\n```\n\n## Performance Monitoring\n\n```php\n$subsetFinder = new SubsetFinder($collection, $subsetCollection);\n$subsetFinder-\u003esolve();\n\n// Get performance metrics\n$metrics = $subsetFinder-\u003egetPerformanceMetrics();\n// [\n//     'execution_time_ms' =\u003e 45.23,\n//     'memory_peak_mb' =\u003e 12.5,\n//     'memory_increase_mb' =\u003e 8.2,\n//     'collection_size' =\u003e 1000,\n//     'subset_count' =\u003e 5,\n//     'found_subsets_count' =\u003e 5,\n//     'remaining_items_count' =\u003e 50\n// ]\n\n// Check solution quality\n$isOptimal = $subsetFinder-\u003eisOptimal();           // true if no remaining items\n$efficiency = $subsetFinder-\u003egetEfficiencyPercentage(); // 95.2%\n```\n\n## Error Handling\n\n```php\nuse Ozdemir\\SubsetFinder\\Exceptions\\InvalidArgumentException;\nuse Ozdemir\\SubsetFinder\\Exceptions\\InsufficientQuantityException;\n\ntry {\n    $subsetFinder = new SubsetFinder($collection, $subsetCollection);\n    $subsetFinder-\u003esolve();\n} catch (InvalidArgumentException $e) {\n    // Handle invalid input (empty collection, invalid items, etc.)\n    Log::error('Invalid subset finder input: ' . $e-\u003egetMessage());\n} catch (InsufficientQuantityException $e) {\n    // Handle insufficient quantities\n    Log::warning('Cannot create subsets: ' . $e-\u003egetMessage());\n}\n```\n\n## Testing\n\n```bash\n# Run tests\ncomposer test\n\n# Run tests with coverage\ncomposer test-coverage\n\n# Run static analysis\ncomposer analyse\n```\n\n## Performance Tips\n\n1. **Use appropriate configuration profiles** for your dataset size\n2. **Enable lazy evaluation** for large collections to reduce memory usage\n3. **Monitor memory usage** and adjust `max_memory_usage` accordingly\n4. **Use meaningful sort fields** to optimize subset selection\n5. **Consider batch processing** for very large datasets\n\n## Advanced Usage\n\n### Custom Logging\n\n```php\nuse Psr\\Log\\LoggerInterface;\n\nclass CustomLogger implements LoggerInterface\n{\n    // Implement logger methods\n}\n\n$subsetFinder = new SubsetFinder(\n    $collection, \n    $subsetCollection, \n    $config, \n    new CustomLogger()\n);\n```\n\n### Memory Management\n\n```php\n// Check memory before processing\nif (memory_get_usage(true) \u003e $config-\u003emaxMemoryUsage) {\n    throw new \\Exception('Insufficient memory for processing');\n}\n\n// Process in batches for very large datasets\n$batchSize = 1000;\nforeach ($collection-\u003echunk($batchSize) as $batch) {\n    // Process batch\n}\n```\n\n## Contributing\n\nContributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis package is open-sourced software licensed under the [MIT License](LICENSE.md).\n\n## Support\n\n- **Documentation**: [GitHub Wiki](https://github.com/n1crack/subset-finder/wiki)\n- **Issues**: [GitHub Issues](https://github.com/n1crack/subset-finder/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/n1crack/subset-finder/discussions)\n\n## Roadmap\n\n### ✅ **Redis Caching Support**\n- **High-performance caching** with Redis integration\n- **Memory-based fallback** when Redis is unavailable\n- **Smart cache key generation** based on input data\n- **Configurable TTL** and cache management\n- **Automatic fallback** to memory cache on Redis failure\n\n### ✅ **Parallel Processing**\n- **Multi-process subset finding** for large datasets\n- **Intelligent chunking** with optimal size calculation\n- **System-aware process limits** based on CPU and memory\n- **Simulated parallel processing** for development environments\n- **Performance metrics** for parallel operations\n\n### ✅ **Weighted Subset Selection**\n- **Multi-criteria optimization** with configurable weights\n- **Advanced constraint handling** (ranges, custom functions)\n- **Efficiency scoring** and ranking algorithms\n- **Statistical analysis** with quartiles and distributions\n- **Real-world optimization** scenarios (e-commerce, inventory)\n\n### 🔄 **In Development**\n- [ ] Machine learning-based optimization\n- [ ] GraphQL integration\n- [ ] Performance benchmarking tools\n- [ ] More configuration profiles\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn1crack%2Fsubset-finder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn1crack%2Fsubset-finder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn1crack%2Fsubset-finder/lists"}