Merge pull request #2 from subhashladumor1/dev

docs .md file

Author: subhashladumor1

README.md

@@ -1,19 +1,23 @@
 {
     "name": "subhashladumor/laravel-helperbox",
-    "description": "? Laravel HelperBox packs 600+ advanced helpers - SQL optimization, caching, APIs, AI tools, arrays, strings, Blade & model utilities. ?? Save time, boost performance & simplify coding for every project, from startups to enterprise.",
+    "description": "Laravel HelperBox packs 600+ advanced helpers - SQL optimization, caching, APIs, AI tools, arrays, strings, Blade & model utilities. ?? Save time, boost performance & simplify coding for every project, from startups to enterprise.",
     "type": "library",
     "license": "MIT",
-    "autoload": {
-        "psr-4": {
-            "Subhashladumor\\LaravelHelperbox\\": "src/"
-        }
-    },
+    "version":"1.0.1",
+    "keywords": [
+        "laravel",
+        "docker",
+        "ci-cd",
+        "github-actions",
+        "devops",
+        "deployment",
+        "automation"
+    ],
     "authors": [
         {
             "name": "Subhash Ladumor"
         }
     ],
-    "minimum-stability": "stable",
     "require": {
         "php": "^8.0",
         "illuminate/support": "^9.0|^10.0|^11.0|^12.0",
@@ -32,5 +36,18 @@
                 "Subhashladumor\\LaravelHelperbox\\HelperServiceProvider"
             ]
         }
-    }
+    },
+    "autoload": {
+        "psr-4": {
+            "Subhashladumor\\LaravelHelperbox\\": "src/"
+        }
+    },
+    "scripts": {
+        "test": "phpunit",
+        "test-coverage": "phpunit --coverage-html coverage",
+        "cs-check": "phpcs",
+        "cs-fix": "phpcbf"
+    },
+    "minimum-stability": "stable",
+    "prefer-stable": true
 }

composer.json

@@ -0,0 +1,37 @@
+### AdvancedAlgorithmHelpers
+
+Heaps, graphs, tries, segment trees, Fenwick trees, matrices, and more.
+
+#### Function Index
+
+- array_to_heap(array $array, bool $maxHeap = true): array
+- heap_extract_min(array &$heap)
+- heap_extract_max(array &$heap)
+- graph_shortest_path(array $graph, $start, $end): array|false
+- graph_has_cycle(array $graph, bool $directed = true): bool
+- graph_topological_sort(array $graph): array|false
+- union_find_create(int $n): array
+- union_find_union(array &$uf, int $a, int $b): void
+- union_find_find(array &$uf, int $x): int
+- trie_insert(array &$trie, string $word): void
+- trie_search(array $trie, string $word): bool
+- trie_prefix_search(array $trie, string $prefix): array
+- segment_tree_build(array $array): array
+- segment_tree_query(array $tree, int $l, int $r): int
+- segment_tree_update(array &$tree, int $index, int $value): void
+- fenwick_tree_build(array $array): array
+- fenwick_tree_sum(array $tree, int $index): int
+- fenwick_tree_update(array &$tree, int $index, int $delta): void
+- matrix_rotate_90(array $matrix): array
+- matrix_spiral_order(array $matrix): array
+
+Internal helpers exposed in this file (for reference): `heapify`, `hasCycleDFS`, `collectWords`, `buildSegmentTree`, `querySegmentTree`, `updateSegmentTree`, `fenwickUpdate`.
+
+#### Examples
+
+```php
+$heap = array_to_heap([3,1,4,1,5], true);
+$min = heap_extract_min($heap);
+```
+
+

docs/AdvancedAlgorithmHelpers.md

@@ -0,0 +1,25 @@
+### AdvancedCacheHelpers
+
+Advanced caching patterns: stampede prevention, jittered TTLs, tagging, chunked payloads, compression, locks, rate limiting.
+
+#### Function Index
+
+- cache_with_jitter(string $key, int $baseTtl, int $jitterPercent = 10, callable $producer = null)
+- cache_versioned_key(string $baseKey, string|int $version): string
+- cache_remember_tagged(array|string $tags, string $key, int $ttl, callable $producer)
+- cache_invalidate_tags(array|string $tags): void
+- cache_chunked_set(string $keyPrefix, string $payload, int $chunkSize = 900000, int $ttl = 3600): int
+- cache_chunked_get(string $keyPrefix): ?string
+- cache_randomized_ttl(int $ttl, int $spread = 20): int
+- cache_precompute(string $key, int $ttl, callable $producer)
+- cache_invalidate_model(string $modelClass, string|int $id): void
+- cache_json_response(string $key, int $ttl, callable $producer): array
+- cache_lock_run(string $name, int $seconds, callable $callback)
+- rate_limit_check(string $key, int $maxAttempts, int $decaySeconds): bool
+- cache_diff_update(string $key, array $newData, int $ttl = 3600): array
+- cache_compress_set(string $key, mixed $value, int $ttl = 3600): void
+- cache_compress_get(string $key, mixed $default = null): mixed
+- cache_stampeded_guard(string $key, int $ttl, callable $producer)
+- cache_forget_by_prefix(string $prefix): int
+
+

docs/AdvancedCacheHelpers.md

@@ -0,0 +1,13 @@
+### AdvancedDeveloperHelpers
+
+Developer productivity: timing, query tracing, SQL dump, deterministic seeding, and lightweight HTTP mocking.
+
+#### Function Index
+
+- dev_time_callable_ms(callable $fn, int $iterations = 1): array
+- dev_trace_queries(callable $fn): array
+- dev_sql_dump(string $table, array $where = []): string
+- dev_seed_random(int $seed): void
+- dev_http_mock(string $url, array $response, int $status = 200): callable
+
+

docs/AdvancedDeveloperHelpers.md

@@ -0,0 +1,33 @@
+### AdvancedLaravelDatabaseHelpers
+
+High-level DB/Eloquent utilities: cloning, diffing, chunking, upserts, N+1 detection, backups, trends, ranking, and optimization.
+
+#### Function Index
+
+- model_clone($model, array $excludeAttributes = ['id','created_at','updated_at'])
+- model_diff($model1, $model2): array
+- model_to_tree($models, string $parentKey = 'parent_id', string $childrenKey = 'children'): array
+- db_safe_transaction(callable $callback, int $attempts = 1)
+- db_query_log(callable $callback): array
+- db_mass_insert(string $table, array $data, int $chunkSize = 1000): int
+- db_mass_upsert(string $table, array $data, array $uniqueKeys, int $chunkSize = 1000): int
+- db_stream_query($query, callable $callback, int $chunkSize = 1000): int
+- db_detect_n_plus_one($query, array $relations): array
+- db_auto_paginate($query, int $defaultPerPage = 15)
+- db_cache_results($query, string $cacheKey, int $ttl = 3600)
+- db_optimize_select_fields($query, array $fields)
+- db_merge_duplicates(string $table, array $criteria, callable $mergeCallback): int
+- db_detect_outliers(string $table, string $column, float $threshold = 2.0): array
+- db_mask_sensitive_data(array $data, array $sensitiveFields, string $mask = '*'): array
+- db_archive_old_rows(string $sourceTable, string $archiveTable, string $dateColumn, string $cutoffDate): int
+- db_auto_sharding(string $baseTable, string $shardKey, int $shardCount): array
+- db_get_trending_data(string $table, string $dateColumn, string $valueColumn, int $days = 30): array
+- db_rank_by_field($query, string $field, string $rankColumn = 'rank')
+- db_analyze_index_usage(string $table): array
+- db_optimize_table_structure(string $table): array
+- db_export_to_json(string $table, string $filePath, array $conditions = []): bool
+- db_import_from_json(string $table, string $filePath, bool $truncateFirst = false): int
+- db_create_backup(string $backupPath, array $tables = []): bool
+- db_restore_backup(string $backupPath): bool
+
+

docs/AdvancedLaravelDatabaseHelpers.md

@@ -0,0 +1,31 @@
+### AdvancedMathAlgorithmicHelpers
+
+Number theory, linear algebra, FFT, optimization, combinatorics, geometry.
+
+#### Function Index
+
+- math_gcd_extended(int $a, int $b): array
+- math_is_prime_miller_rabin(int $n, int $k = 5): bool
+- math_generate_primes_sieve(int $n): array
+- math_factorial_bigint(int $n): string
+- math_modular_inverse(int $a, int $m): int|false
+- math_modular_pow(int $base, int $exp, int $mod): int
+- math_fibonacci_matrix(int $n): int
+- math_polynomial_evaluate(array $coeffs, float $x): float
+- math_interpolation_lagrange(array $points): array
+- math_determinant(array $matrix): float
+- math_matrix_inverse(array $matrix): array|false
+- math_matrix_multiply(array $a, array $b): array
+- math_convex_hull(array $points): array
+- math_fast_fourier_transform(array $real, array $imag): array
+- math_random_gaussian(float $mean = 0, float $stddev = 1): float
+- math_combinations(array $array, int $k): array
+- math_permutations(array $array): array
+- math_power_set(array $array): array
+- math_knapsack(array $weights, array $values, int $capacity): array
+- math_coin_change(array $coins, int $amount): int
+- math_simplex(array $objective, array $constraints, array $rhs): array|false
+
+Helper functions: `math_polynomial_multiply`, `math_cross_product`, `fft_recursive`, `math_matrix_pow`.
+
+

docs/AdvancedMathAlgorithmicHelpers.md

@@ -0,0 +1,45 @@
+### ApiHttpHelpers
+
+Convenience wrappers around Laravel HTTP client and JSON API responses.
+
+#### Function Index
+
+- http_get_json(string $url, array $headers = []): array|false
+- http_post_json(string $url, array $data, array $headers = []): array|false
+- http_put_json(string $url, array $data, array $headers = []): array|false
+- http_delete_json(string $url, array $headers = []): array|false
+- http_status_message(int $code): string
+- http_is_success(int $code): bool
+- http_is_redirect(int $code): bool
+- http_is_error(int $code): bool
+- api_success(mixed $data = null, string $message = 'OK', int $code = 200)
+- api_error(string $message = 'Error', int $code = 400, mixed $errors = null)
+- api_validation_error(array $errors, string $message = 'Validation failed')
+- api_not_found(string $message = 'Not Found')
+- api_unauthorized(string $message = 'Unauthorized')
+- api_forbidden(string $message = 'Forbidden')
+- api_internal_error(string $message = 'Internal Server Error')
+- api_created(mixed $data = null, string $message = 'Created')
+- api_no_content()
+- api_paginate_response($data, int $page, int $perPage)
+- http_timeout(string $method, string $url, array $options = [], int $timeout = 30)
+- http_retry(string $method, string $url, array $options = [], int $retries = 3)
+- http_with_auth(string $method, string $url, string $token, array $options = [])
+- http_download(string $url, string $path): bool
+- http_upload(string $url, string $filePath, array $headers = []): array|false
+- http_validate_url(string $url): bool
+- http_get_domain(string $url): string|false
+- http_get_path(string $url): string|false
+- http_get_query(string $url): array
+- http_build_query_url(string $url, array $params): string
+- api_rate_limit_exceeded(string $message = 'Rate limit exceeded')
+- api_download_response(string $filePath, ?string $fileName = null)
+
+#### Examples
+
+```php
+$data = http_get_json('https://api.github.com');
+return api_success($data);
+```
+
+

docs/ApiHttpHelpers.md

@@ -0,0 +1,55 @@
+### ArrayHelpers
+
+Practical array utilities for flattening, grouping, plucking, keyed inserts, partitions, CSV conversion, padding, randomization, and more.
+
+#### Function Index
+
+- array_flatten_recursive(array $array, int $depth = 0): array
+- array_to_xml(array $array, string $rootElement = 'root', string $xmlVersion = '1.0', string $encoding = 'UTF-8'): string
+- array_shuffle_assoc(array $array): array
+- array_key_case(array $array, int $case = CASE_LOWER): array
+- array_group_by(array $array, callable|string $key): array
+- array_multi_search(array $array, mixed $search, bool $strict = false): array
+- array_pluck_recursive(array $array, string $key): array
+- array_random_key(array $array)
+- array_random_value(array $array)
+- array_insert_after(array $array, mixed $key, mixed $newKey, mixed $newValue): array
+- array_insert_before(array $array, mixed $key, mixed $newKey, mixed $newValue): array
+- array_first_key(array $array)
+- array_last_key(array $array)
+- array_first_value(array $array)
+- array_last_value(array $array)
+- array_partition(array $array, callable $callback): array
+- array_is_assoc(array $array): bool
+- array_is_list(array $array): bool
+- array_only_keys(array $array, array $keys): array
+- array_except_keys(array $array, array $keys): array
+- array_merge_recursive_distinct(array $array1, array $array2): array
+- array_diff_recursive(array $array1, array $array2): array
+- array_to_csv(array $array, string $delimiter = ',', string $enclosure = '"'): string
+- array_from_csv(string $csv, string $delimiter = ',', string $enclosure = '"'): array
+- array_split_chunks(array $array, int $size): array
+- array_pad_left(array $array, int $size, mixed $value = null): array
+- array_pad_right(array $array, int $size, mixed $value = null): array
+- array_to_collection(array $array): \Illuminate\Support\Collection
+- array_random_subset(array $array, int $count): array
+- array_to_object(array $array): object
+
+#### Examples
+
+```php
+$flat = array_flatten_recursive([[1, [2]], 3]); // [1,2,3]
+
+$groups = array_group_by([
+  ['id' => 1, 'role' => 'admin'],
+  ['id' => 2, 'role' => 'user'],
+], 'role');
+// ['admin' => [...], 'user' => [...]]
+
+$csv = array_to_csv([
+  ['id' => 1, 'name' => 'A'],
+  ['id' => 2, 'name' => 'B'],
+]);
+```
+
+

docs/ArrayHelpers.md

@@ -0,0 +1,42 @@
+### BladeHelpers
+
+Blade-friendly conditionals, formatting helpers, directives support, and UI attributes.
+
+#### Function Index
+
+- blade_if_route(string|array $route): bool
+- blade_if_controller(string|array $controller): bool
+- blade_if_action(string|array $action): bool
+- blade_if_role(string|array $role): bool
+- blade_if_permission(string|array $permission): bool
+- blade_format_date(mixed $date, string $format = 'Y-m-d H:i:s'): string
+- blade_asset_version(string $file): string
+- blade_inline_svg(string $path, array $attributes = []): string
+- blade_component_exists(string $name): bool
+- blade_render_markdown(string $text): string
+- blade_loop_index(): int
+- blade_include_if_exists(string $view, array $data = []): string
+- blade_old_value(string $key, mixed $default = null)
+- blade_error_message(string $field): string
+- blade_has_error(string $field): bool
+- blade_csrf_token(): string
+- blade_method_field(string $method): string
+- blade_route_url(string $name, array $parameters = []): string
+- blade_active_class(string|array $route, string $class = 'active'): string
+- blade_checked(mixed $value, mixed $checked): string
+- blade_selected(mixed $value, mixed $selected): string
+- blade_disabled(bool $condition): string
+- blade_readonly(bool $condition): string
+- blade_required(bool $condition): string
+- blade_placeholder(string $field, string $default = ''): string
+- blade_help_text(string $field, string $default = ''): string
+
+#### Examples
+
+```blade
+<li class="{{ blade_active_class('dashboard') }}">...</li>
+@if(blade_if_role('admin')) ... @endif
+{!! blade_inline_svg('icons/logo.svg', ['class' => 'h-6']) !!}
+```
+
+