start-vibing-stacks 1.9.0 → 1.9.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/ui.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Start Vibing Stacks — Terminal UI
|
|
3
3
|
*/
|
|
4
4
|
import chalk from 'chalk';
|
|
5
|
-
const VERSION = '1.9.
|
|
5
|
+
const VERSION = '1.9.2';
|
|
6
6
|
const gradient = (text) => {
|
|
7
7
|
const colors = [chalk.hex('#FF6B6B'), chalk.hex('#FF8E53'), chalk.hex('#FFBD2E'), chalk.hex('#48BB78'), chalk.hex('#4299E1'), chalk.hex('#9F7AEA')];
|
|
8
8
|
return text.split('').map((c, i) => colors[i % colors.length](c)).join('');
|
package/package.json
CHANGED
|
@@ -1,94 +1,273 @@
|
|
|
1
|
-
#
|
|
1
|
+
# TailwindCSS 4 — CSS-First Design System
|
|
2
2
|
|
|
3
|
-
**ALWAYS invoke when writing Tailwind
|
|
3
|
+
**ALWAYS invoke when writing Tailwind classes, theming, or responsive layouts.**
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## What Changed (v3 → v4)
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
| v3 (Legacy) | v4 (Current) |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `tailwind.config.js` | CSS `@theme` directive |
|
|
10
|
+
| PostCSS plugin | Oxide engine (10x faster) |
|
|
11
|
+
| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
|
|
12
|
+
| Colors in JS config | Colors as CSS variables |
|
|
13
|
+
| `@apply` everywhere | Components > `@apply` |
|
|
14
|
+
|
|
15
|
+
## Setup (v4)
|
|
16
|
+
|
|
17
|
+
```css
|
|
18
|
+
/* resources/css/app.css (Laravel + Inertia) */
|
|
19
|
+
@import "tailwindcss";
|
|
20
|
+
|
|
21
|
+
@theme {
|
|
22
|
+
/* ─── Semantic Colors (OKLCH for perceptual uniformity) ─── */
|
|
23
|
+
--color-primary: oklch(0.55 0.15 250);
|
|
24
|
+
--color-primary-foreground: oklch(0.98 0 0);
|
|
25
|
+
--color-secondary: oklch(0.75 0.05 250);
|
|
26
|
+
--color-secondary-foreground: oklch(0.15 0 0);
|
|
27
|
+
--color-destructive: oklch(0.55 0.2 25);
|
|
28
|
+
--color-destructive-foreground: oklch(0.98 0 0);
|
|
29
|
+
|
|
30
|
+
--color-background: oklch(0.99 0 0);
|
|
31
|
+
--color-foreground: oklch(0.15 0 0);
|
|
32
|
+
--color-muted: oklch(0.95 0.01 250);
|
|
33
|
+
--color-muted-foreground: oklch(0.45 0.02 250);
|
|
34
|
+
--color-border: oklch(0.90 0.01 250);
|
|
35
|
+
--color-ring: oklch(0.55 0.15 250);
|
|
36
|
+
|
|
37
|
+
--color-surface: oklch(0.98 0 0);
|
|
38
|
+
--color-surface-raised: oklch(1 0 0);
|
|
39
|
+
|
|
40
|
+
/* ─── Typography ─── */
|
|
41
|
+
--font-sans: 'Inter', system-ui, sans-serif;
|
|
42
|
+
--font-mono: 'JetBrains Mono', monospace;
|
|
43
|
+
|
|
44
|
+
/* ─── Spacing ─── */
|
|
45
|
+
--spacing-page: 1rem;
|
|
46
|
+
|
|
47
|
+
/* ─── Border Radius ─── */
|
|
48
|
+
--radius-sm: 0.375rem;
|
|
49
|
+
--radius-md: 0.5rem;
|
|
50
|
+
--radius-lg: 0.75rem;
|
|
51
|
+
--radius-xl: 1rem;
|
|
52
|
+
|
|
53
|
+
/* ─── Shadows ─── */
|
|
54
|
+
--shadow-sm: 0 1px 2px oklch(0 0 0 / 0.05);
|
|
55
|
+
--shadow-md: 0 4px 6px oklch(0 0 0 / 0.07);
|
|
56
|
+
--shadow-lg: 0 10px 15px oklch(0 0 0 / 0.1);
|
|
57
|
+
|
|
58
|
+
/* ─── Animations ─── */
|
|
59
|
+
--animate-fade-in: fade-in 0.2s ease-out;
|
|
60
|
+
--animate-slide-up: slide-up 0.3s ease-out;
|
|
61
|
+
--animate-slide-down: slide-down 0.3s ease-out;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/* ─── Dark Mode Override ─── */
|
|
65
|
+
@theme dark {
|
|
66
|
+
--color-background: oklch(0.13 0.01 250);
|
|
67
|
+
--color-foreground: oklch(0.95 0 0);
|
|
68
|
+
--color-surface: oklch(0.17 0.01 250);
|
|
69
|
+
--color-surface-raised: oklch(0.21 0.01 250);
|
|
70
|
+
--color-muted: oklch(0.22 0.02 250);
|
|
71
|
+
--color-muted-foreground: oklch(0.65 0.02 250);
|
|
72
|
+
--color-border: oklch(0.28 0.02 250);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/* ─── Keyframes ─── */
|
|
76
|
+
@keyframes fade-in {
|
|
77
|
+
from { opacity: 0; }
|
|
78
|
+
to { opacity: 1; }
|
|
79
|
+
}
|
|
80
|
+
@keyframes slide-up {
|
|
81
|
+
from { opacity: 0; transform: translateY(8px); }
|
|
82
|
+
to { opacity: 1; transform: translateY(0); }
|
|
83
|
+
}
|
|
84
|
+
@keyframes slide-down {
|
|
85
|
+
from { opacity: 0; transform: translateY(-8px); }
|
|
86
|
+
to { opacity: 1; transform: translateY(0); }
|
|
87
|
+
}
|
|
9
88
|
```
|
|
10
89
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
{/* Mobile: full → Tablet: half → Desktop: third → Large: quarter */}
|
|
14
|
-
</div>
|
|
90
|
+
## Color Token Architecture
|
|
91
|
+
|
|
15
92
|
```
|
|
93
|
+
Layer 1 — Primitive: oklch(0.55 0.15 250) (raw values)
|
|
94
|
+
Layer 2 — Semantic: --color-primary (purpose-based)
|
|
95
|
+
Layer 3 — Component: className="bg-primary" (usage in JSX)
|
|
16
96
|
|
|
17
|
-
|
|
97
|
+
Usage in Tailwind classes:
|
|
98
|
+
bg-primary text-primary-foreground
|
|
99
|
+
bg-destructive text-destructive-foreground
|
|
100
|
+
bg-muted text-muted-foreground
|
|
101
|
+
bg-surface border-border
|
|
102
|
+
```
|
|
18
103
|
|
|
19
|
-
|
|
20
|
-
```tsx
|
|
21
|
-
// Center
|
|
22
|
-
<div className="flex items-center justify-center h-screen" />
|
|
104
|
+
## Mobile-First Responsive
|
|
23
105
|
|
|
24
|
-
|
|
25
|
-
|
|
106
|
+
```
|
|
107
|
+
Breakpoints (min-width):
|
|
108
|
+
(none) → 0px Mobile base
|
|
109
|
+
sm: → 640px Large phone
|
|
110
|
+
md: → 768px Tablet
|
|
111
|
+
lg: → 1024px Laptop
|
|
112
|
+
xl: → 1280px Desktop
|
|
113
|
+
2xl: → 1536px Large desktop
|
|
26
114
|
```
|
|
27
115
|
|
|
28
|
-
### Grid
|
|
29
116
|
```tsx
|
|
30
|
-
|
|
31
|
-
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"
|
|
117
|
+
{/* Mobile: stack → Tablet: 2 cols → Desktop: 3 cols */}
|
|
118
|
+
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
|
|
32
119
|
|
|
33
|
-
|
|
34
|
-
<div className="
|
|
120
|
+
{/* Mobile: full width → Desktop: sidebar layout */}
|
|
121
|
+
<div className="flex flex-col lg:flex-row gap-6">
|
|
122
|
+
<aside className="w-full lg:w-64 shrink-0">Sidebar</aside>
|
|
123
|
+
<main className="flex-1">Content</main>
|
|
124
|
+
</div>
|
|
35
125
|
```
|
|
36
126
|
|
|
37
|
-
##
|
|
127
|
+
## Container Queries (v4 Native)
|
|
38
128
|
|
|
39
129
|
```tsx
|
|
40
|
-
|
|
41
|
-
|
|
130
|
+
{/* Parent defines container */}
|
|
131
|
+
<div className="@container">
|
|
132
|
+
{/* Children respond to PARENT width, not viewport */}
|
|
133
|
+
<div className="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3 gap-4">
|
|
134
|
+
<Card />
|
|
135
|
+
</div>
|
|
136
|
+
</div>
|
|
137
|
+
|
|
138
|
+
{/* Named containers for specificity */}
|
|
139
|
+
<div className="@container/card">
|
|
140
|
+
<h2 className="text-sm @md/card:text-lg">Title</h2>
|
|
42
141
|
</div>
|
|
43
142
|
```
|
|
44
143
|
|
|
144
|
+
**Rule:** Use container queries for **reusable components** (cards, widgets). Use viewport breakpoints for **page-level layouts**.
|
|
145
|
+
|
|
45
146
|
## Component Patterns
|
|
46
147
|
|
|
47
|
-
###
|
|
148
|
+
### Button
|
|
149
|
+
|
|
48
150
|
```tsx
|
|
49
|
-
|
|
151
|
+
const buttonVariants = {
|
|
152
|
+
base: "inline-flex items-center justify-center font-medium rounded-md transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed",
|
|
153
|
+
variant: {
|
|
154
|
+
primary: "bg-primary text-primary-foreground hover:bg-primary/90",
|
|
155
|
+
secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
|
|
156
|
+
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
|
|
157
|
+
outline: "border border-border bg-transparent hover:bg-muted",
|
|
158
|
+
ghost: "hover:bg-muted",
|
|
159
|
+
},
|
|
160
|
+
size: {
|
|
161
|
+
sm: "h-8 px-3 text-sm",
|
|
162
|
+
md: "h-10 px-4 text-sm",
|
|
163
|
+
lg: "h-12 px-6 text-base",
|
|
164
|
+
},
|
|
165
|
+
};
|
|
50
166
|
```
|
|
51
167
|
|
|
52
|
-
###
|
|
168
|
+
### Card
|
|
169
|
+
|
|
53
170
|
```tsx
|
|
54
|
-
<
|
|
171
|
+
<div className="bg-surface-raised rounded-lg border border-border shadow-sm p-6 hover:shadow-md transition-shadow">
|
|
172
|
+
<h3 className="text-lg font-semibold text-foreground">Title</h3>
|
|
173
|
+
<p className="mt-2 text-muted-foreground">Description</p>
|
|
174
|
+
</div>
|
|
55
175
|
```
|
|
56
176
|
|
|
57
177
|
### Input
|
|
178
|
+
|
|
58
179
|
```tsx
|
|
59
|
-
<input className="w-full px-3
|
|
180
|
+
<input className="w-full h-10 px-3 rounded-md border border-border bg-background text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent transition-colors" />
|
|
60
181
|
```
|
|
61
182
|
|
|
62
|
-
|
|
183
|
+
### Table (responsive)
|
|
63
184
|
|
|
64
185
|
```tsx
|
|
65
|
-
|
|
66
|
-
<div className="
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
186
|
+
{/* Mobile: card layout → Desktop: table */}
|
|
187
|
+
<div className="hidden md:block">
|
|
188
|
+
<table className="w-full text-sm">
|
|
189
|
+
<thead className="border-b border-border">
|
|
190
|
+
<tr className="text-left text-muted-foreground">
|
|
191
|
+
<th className="p-3 font-medium">Name</th>
|
|
192
|
+
</tr>
|
|
193
|
+
</thead>
|
|
194
|
+
</table>
|
|
195
|
+
</div>
|
|
196
|
+
<div className="md:hidden space-y-3">
|
|
197
|
+
{/* Card layout for mobile */}
|
|
198
|
+
</div>
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## Dark Mode
|
|
202
|
+
|
|
203
|
+
```tsx
|
|
204
|
+
{/* Automatic with semantic tokens */}
|
|
205
|
+
<div className="bg-background text-foreground">
|
|
206
|
+
<p className="text-muted-foreground">Always adapts</p>
|
|
207
|
+
<div className="border-border bg-surface">Card</div>
|
|
208
|
+
</div>
|
|
209
|
+
|
|
210
|
+
{/* Toggle button */}
|
|
211
|
+
<button onClick={() => document.documentElement.classList.toggle('dark')}>
|
|
212
|
+
Toggle Theme
|
|
213
|
+
</button>
|
|
79
214
|
```
|
|
80
215
|
|
|
81
|
-
|
|
216
|
+
**Rule:** Use semantic tokens (`bg-background`, `text-foreground`) instead of explicit dark classes. The `@theme dark` block handles everything.
|
|
217
|
+
|
|
218
|
+
## Show/Hide
|
|
82
219
|
|
|
83
220
|
```tsx
|
|
84
221
|
<div className="hidden lg:block">Desktop only</div>
|
|
85
|
-
<div className="
|
|
222
|
+
<div className="lg:hidden">Mobile only</div>
|
|
86
223
|
<span className="sr-only">Screen reader only</span>
|
|
87
224
|
```
|
|
88
225
|
|
|
226
|
+
## Auto-fit Grid
|
|
227
|
+
|
|
228
|
+
```tsx
|
|
229
|
+
{/* Cards that auto-wrap based on available space */}
|
|
230
|
+
<div className="grid grid-cols-[repeat(auto-fit,minmax(280px,1fr))] gap-4">
|
|
231
|
+
{items.map(item => <Card key={item.id} {...item} />)}
|
|
232
|
+
</div>
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
## Animations
|
|
236
|
+
|
|
237
|
+
```tsx
|
|
238
|
+
<div className="animate-fade-in">Fades in on mount</div>
|
|
239
|
+
<div className="animate-slide-up">Slides up on mount</div>
|
|
240
|
+
<Loader className="h-5 w-5 animate-spin" />
|
|
241
|
+
<div className="h-4 w-24 bg-muted animate-pulse rounded" /> {/* Skeleton */}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
## Spacing Consistency
|
|
245
|
+
|
|
246
|
+
```
|
|
247
|
+
Use the 4px scale consistently:
|
|
248
|
+
gap-1 = 4px p-1 = 4px
|
|
249
|
+
gap-2 = 8px p-2 = 8px
|
|
250
|
+
gap-3 = 12px p-3 = 12px
|
|
251
|
+
gap-4 = 16px p-4 = 16px
|
|
252
|
+
gap-6 = 24px p-6 = 24px
|
|
253
|
+
gap-8 = 32px p-8 = 32px
|
|
254
|
+
|
|
255
|
+
Page padding: px-4 md:px-6 lg:px-8
|
|
256
|
+
Section gaps: space-y-6 md:space-y-8
|
|
257
|
+
Card padding: p-4 md:p-6
|
|
258
|
+
```
|
|
259
|
+
|
|
89
260
|
## FORBIDDEN
|
|
90
261
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
262
|
+
| ❌ Don't | ✅ Do |
|
|
263
|
+
|---|---|
|
|
264
|
+
| `tailwind.config.js` in v4 | `@theme` in CSS |
|
|
265
|
+
| `@apply` for everything | React components |
|
|
266
|
+
| `!important` | Fix specificity |
|
|
267
|
+
| `style={{ color: 'red' }}` | `text-destructive` |
|
|
268
|
+
| Arbitrary values for tokens | Define in `@theme` |
|
|
269
|
+
| `bg-white dark:bg-gray-900` | `bg-background` (semantic) |
|
|
270
|
+
| `@tailwind base` | `@import "tailwindcss"` (v4) |
|
|
271
|
+
| Dynamic class strings | Static complete strings (purge-safe) |
|
|
272
|
+
| `text-[#FF5733]` inline | `--color-accent` in `@theme` |
|
|
273
|
+
| Inconsistent spacing | Follow 4px scale |
|
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
# MariaDB + Octane — Database Patterns for Persistent Workers
|
|
2
|
+
|
|
3
|
+
**ALWAYS invoke when writing queries, migrations, models, or DB config in Laravel Octane.**
|
|
4
|
+
|
|
5
|
+
## Why Octane Changes Everything
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
Traditional PHP: Octane (RoadRunner):
|
|
9
|
+
┌──────────┐ ┌──────────────────────┐
|
|
10
|
+
│ Request → │ │ Worker boots ONCE │
|
|
11
|
+
│ Boot app │ │ ↓ │
|
|
12
|
+
│ DB connect│ │ Request 1 → process │
|
|
13
|
+
│ Process │ │ Request 2 → process │ ← SAME connection
|
|
14
|
+
│ DB close │ │ Request 3 → process │ ← SAME state
|
|
15
|
+
│ Die │ │ ...500 requests... │
|
|
16
|
+
└──────────┘ │ Worker restarts │
|
|
17
|
+
└──────────────────────┘
|
|
18
|
+
|
|
19
|
+
Problems in Octane:
|
|
20
|
+
- Connection stays open → stale connections, gone away errors
|
|
21
|
+
- Transaction leaks → uncommitted TX bleeds to next request
|
|
22
|
+
- Query builder state → leftover bindings
|
|
23
|
+
- String truncation → silent data loss in strict mode OFF
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Connection Configuration
|
|
27
|
+
|
|
28
|
+
```php
|
|
29
|
+
// config/database.php
|
|
30
|
+
'mysql' => [
|
|
31
|
+
'driver' => 'mysql',
|
|
32
|
+
'host' => env('DB_HOST', '127.0.0.1'),
|
|
33
|
+
'port' => env('DB_PORT', '3306'),
|
|
34
|
+
'database' => env('DB_DATABASE'),
|
|
35
|
+
'username' => env('DB_USERNAME'),
|
|
36
|
+
'password' => env('DB_PASSWORD'),
|
|
37
|
+
'charset' => 'utf8mb4',
|
|
38
|
+
'collation' => 'utf8mb4_unicode_ci',
|
|
39
|
+
'prefix' => '',
|
|
40
|
+
'strict' => true, // ← MANDATORY
|
|
41
|
+
'engine' => 'InnoDB',
|
|
42
|
+
'options' => [
|
|
43
|
+
PDO::ATTR_PERSISTENT => true, // ← Octane reuses connections
|
|
44
|
+
PDO::ATTR_EMULATE_PREPARES => false, // ← Real prepared statements
|
|
45
|
+
PDO::ATTR_STRINGIFY_FETCHES => false, // ← Preserve int/float types
|
|
46
|
+
PDO::MYSQL_ATTR_FOUND_ROWS => true, // ← Accurate affected rows
|
|
47
|
+
],
|
|
48
|
+
'modes' => [
|
|
49
|
+
'STRICT_TRANS_TABLES', // ← Errors instead of truncation
|
|
50
|
+
'NO_ZERO_IN_DATE', // ← No 0000-00-00 dates
|
|
51
|
+
'NO_ZERO_DATE',
|
|
52
|
+
'ERROR_FOR_DIVISION_BY_ZERO',
|
|
53
|
+
'NO_ENGINE_SUBSTITUTION',
|
|
54
|
+
'ONLY_FULL_GROUP_BY', // ← Force explicit GROUP BY
|
|
55
|
+
],
|
|
56
|
+
],
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Why `strict => true` + SQL Modes
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
strict: false (DEFAULT MariaDB):
|
|
63
|
+
INSERT INTO users (name) VALUES ('This is a very long name that exceeds the column limit')
|
|
64
|
+
→ Silently TRUNCATES to column length! No error! DATA LOST!
|
|
65
|
+
|
|
66
|
+
strict: true (OUR STANDARD):
|
|
67
|
+
→ ERROR 1406: Data too long for column 'name'
|
|
68
|
+
→ You KNOW the problem immediately
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**Rule:** `strict => true` is NON-NEGOTIABLE. Every silent truncation is a bug waiting to explode.
|
|
72
|
+
|
|
73
|
+
## Octane Connection Flush (MANDATORY)
|
|
74
|
+
|
|
75
|
+
```php
|
|
76
|
+
// app/Providers/AppServiceProvider.php
|
|
77
|
+
use Laravel\Octane\Facades\Octane;
|
|
78
|
+
|
|
79
|
+
public function boot(): void
|
|
80
|
+
{
|
|
81
|
+
// Flush stale connections between requests
|
|
82
|
+
Octane::prepare(function ($sandbox) {
|
|
83
|
+
$sandbox->flushDatabaseConnections();
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
// Also flush on tick (long-running operations)
|
|
87
|
+
Octane::tick('db-health', function () {
|
|
88
|
+
try {
|
|
89
|
+
DB::connection()->getPdo();
|
|
90
|
+
} catch (\Exception $e) {
|
|
91
|
+
DB::reconnect();
|
|
92
|
+
}
|
|
93
|
+
})->seconds(30);
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Migration Patterns
|
|
98
|
+
|
|
99
|
+
### Column Definitions — Be Explicit
|
|
100
|
+
|
|
101
|
+
```php
|
|
102
|
+
// ✅ ALWAYS define exact lengths — no surprises with strict mode
|
|
103
|
+
Schema::create('leads', function (Blueprint $table) {
|
|
104
|
+
$table->uuid('id')->primary();
|
|
105
|
+
|
|
106
|
+
// Strings: ALWAYS define max length
|
|
107
|
+
$table->string('name', 255); // varchar(255)
|
|
108
|
+
$table->string('email', 320); // RFC 5321 max email
|
|
109
|
+
$table->string('phone', 20); // E.164 max
|
|
110
|
+
$table->string('status', 30); // enum-like but flexible
|
|
111
|
+
$table->string('country_code', 3); // ISO 3166-1 alpha-2/3
|
|
112
|
+
$table->string('currency', 3); // ISO 4217
|
|
113
|
+
|
|
114
|
+
// Use text() for unbounded content
|
|
115
|
+
$table->text('notes'); // 64KB
|
|
116
|
+
$table->mediumText('description'); // 16MB
|
|
117
|
+
$table->longText('raw_payload'); // 4GB
|
|
118
|
+
|
|
119
|
+
// Decimals: ALWAYS precision + scale
|
|
120
|
+
$table->decimal('price', 10, 2); // 99,999,999.99
|
|
121
|
+
$table->decimal('commission_rate', 5, 4); // 0.0000 to 9.9999
|
|
122
|
+
$table->unsignedBigInteger('impressions')->default(0);
|
|
123
|
+
|
|
124
|
+
// Dates
|
|
125
|
+
$table->timestamp('converted_at')->nullable();
|
|
126
|
+
$table->timestamps(); // created_at, updated_at
|
|
127
|
+
$table->softDeletes(); // deleted_at
|
|
128
|
+
|
|
129
|
+
// JSON (MariaDB 10.2+)
|
|
130
|
+
$table->json('metadata')->nullable();
|
|
131
|
+
|
|
132
|
+
// Indexes
|
|
133
|
+
$table->index('status');
|
|
134
|
+
$table->index(['status', 'created_at']); // Composite for common queries
|
|
135
|
+
$table->unique('email');
|
|
136
|
+
});
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Index Strategy for MariaDB
|
|
140
|
+
|
|
141
|
+
```php
|
|
142
|
+
// ✅ Composite indexes — leftmost prefix rule
|
|
143
|
+
$table->index(['user_id', 'status', 'created_at']);
|
|
144
|
+
// Covers: WHERE user_id = ?
|
|
145
|
+
// Covers: WHERE user_id = ? AND status = ?
|
|
146
|
+
// Covers: WHERE user_id = ? AND status = ? ORDER BY created_at
|
|
147
|
+
// Does NOT cover: WHERE status = ? (user_id not in query)
|
|
148
|
+
|
|
149
|
+
// ✅ Covering index for frequent queries
|
|
150
|
+
$table->index(['domain_id', 'status', 'created_at', 'id'], 'idx_leads_dashboard');
|
|
151
|
+
|
|
152
|
+
// ✅ Partial-like with generated column (MariaDB 10.2+)
|
|
153
|
+
// For: WHERE JSON_EXTRACT(metadata, '$.source') = 'google'
|
|
154
|
+
$table->string('metadata_source', 50)->virtualAs("JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.source'))");
|
|
155
|
+
$table->index('metadata_source');
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Eloquent Patterns for Octane
|
|
159
|
+
|
|
160
|
+
### Scoped Queries (avoid stale state)
|
|
161
|
+
|
|
162
|
+
```php
|
|
163
|
+
class Lead extends Model
|
|
164
|
+
{
|
|
165
|
+
use HasUuids;
|
|
166
|
+
|
|
167
|
+
// ✅ Scopes — reusable, composable
|
|
168
|
+
public function scopeActive(Builder $query): Builder
|
|
169
|
+
{
|
|
170
|
+
return $query->where('status', 'active');
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
public function scopeForUser(Builder $query, string $userId): Builder
|
|
174
|
+
{
|
|
175
|
+
return $query->where('user_id', $userId);
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
public function scopeCreatedBetween(Builder $query, Carbon $from, Carbon $to): Builder
|
|
179
|
+
{
|
|
180
|
+
return $query->whereBetween('created_at', [$from, $to]);
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
// Usage (always fresh query, no state leaks):
|
|
185
|
+
Lead::query()
|
|
186
|
+
->active()
|
|
187
|
+
->forUser($request->user()->id)
|
|
188
|
+
->createdBetween(now()->subDays(30), now())
|
|
189
|
+
->paginate(20);
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### N+1 Prevention
|
|
193
|
+
|
|
194
|
+
```php
|
|
195
|
+
// ✅ ALWAYS eager load relationships
|
|
196
|
+
class LeadController extends Controller
|
|
197
|
+
{
|
|
198
|
+
public function index(Request $request): JsonResponse
|
|
199
|
+
{
|
|
200
|
+
$leads = Lead::query()
|
|
201
|
+
->with(['domain:id,name', 'user:id,name,email']) // Select only needed columns
|
|
202
|
+
->select('id', 'name', 'email', 'status', 'domain_id', 'user_id', 'created_at')
|
|
203
|
+
->forUser($request->user()->id)
|
|
204
|
+
->latest()
|
|
205
|
+
->paginate(20);
|
|
206
|
+
|
|
207
|
+
return LeadResource::collection($leads);
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
// ❌ NEVER in Octane (N+1 with persistent connections = compounding slowness)
|
|
212
|
+
foreach ($leads as $lead) {
|
|
213
|
+
echo $lead->domain->name; // N+1 query PER lead, PER request, ALL DAY
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Bulk Operations (Octane-safe)
|
|
218
|
+
|
|
219
|
+
```php
|
|
220
|
+
// ✅ Chunked processing — controls memory in long-lived worker
|
|
221
|
+
Lead::query()
|
|
222
|
+
->where('status', 'pending')
|
|
223
|
+
->chunkById(500, function ($leads) {
|
|
224
|
+
foreach ($leads as $lead) {
|
|
225
|
+
ProcessLeadJob::dispatch($lead);
|
|
226
|
+
}
|
|
227
|
+
});
|
|
228
|
+
|
|
229
|
+
// ✅ Bulk insert (single query)
|
|
230
|
+
Lead::insert(
|
|
231
|
+
collect($rows)->map(fn ($row) => [
|
|
232
|
+
'id' => Str::uuid()->toString(),
|
|
233
|
+
'name' => $row['name'],
|
|
234
|
+
'email' => $row['email'],
|
|
235
|
+
'created_at' => now(),
|
|
236
|
+
'updated_at' => now(),
|
|
237
|
+
])->toArray()
|
|
238
|
+
);
|
|
239
|
+
|
|
240
|
+
// ✅ Bulk update
|
|
241
|
+
Lead::query()
|
|
242
|
+
->whereIn('id', $ids)
|
|
243
|
+
->update(['status' => 'processed', 'processed_at' => now()]);
|
|
244
|
+
|
|
245
|
+
// ❌ NEVER in Octane (memory grows with each request)
|
|
246
|
+
$allLeads = Lead::all(); // Loads EVERYTHING into worker memory
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
### Transaction Safety in Octane
|
|
250
|
+
|
|
251
|
+
```php
|
|
252
|
+
// ✅ Always explicit transactions with try/catch
|
|
253
|
+
// In Octane, an uncaught exception leaves the TX open for the NEXT request!
|
|
254
|
+
try {
|
|
255
|
+
DB::beginTransaction();
|
|
256
|
+
|
|
257
|
+
$lead = Lead::create($validated);
|
|
258
|
+
$lead->attempts()->create(['status' => 'new']);
|
|
259
|
+
ConversionService::fire($lead);
|
|
260
|
+
|
|
261
|
+
DB::commit();
|
|
262
|
+
} catch (\Throwable $e) {
|
|
263
|
+
DB::rollBack(); // ← CRITICAL in Octane — prevents TX leak
|
|
264
|
+
report($e);
|
|
265
|
+
throw $e;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
// ✅ Or use the closure syntax (auto-rollback on exception)
|
|
269
|
+
$lead = DB::transaction(function () use ($validated) {
|
|
270
|
+
$lead = Lead::create($validated);
|
|
271
|
+
$lead->attempts()->create(['status' => 'new']);
|
|
272
|
+
return $lead;
|
|
273
|
+
}, attempts: 3); // Retry on deadlock
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## Query Performance
|
|
277
|
+
|
|
278
|
+
### Explain Before Deploy
|
|
279
|
+
|
|
280
|
+
```php
|
|
281
|
+
// In Tinker or test:
|
|
282
|
+
DB::enableQueryLog();
|
|
283
|
+
$leads = Lead::query()->active()->forUser($userId)->paginate(20);
|
|
284
|
+
$queries = DB::getQueryLog();
|
|
285
|
+
|
|
286
|
+
// Check for full table scans:
|
|
287
|
+
// EXPLAIN SELECT * FROM leads WHERE user_id = ? AND status = 'active'
|
|
288
|
+
// Look for: type=ref or type=range (GOOD), type=ALL (BAD — full scan)
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
### Pagination (NEVER offset for large tables)
|
|
292
|
+
|
|
293
|
+
```php
|
|
294
|
+
// ✅ Cursor pagination (fast on large tables)
|
|
295
|
+
$leads = Lead::query()
|
|
296
|
+
->where('user_id', $userId)
|
|
297
|
+
->orderBy('id')
|
|
298
|
+
->cursorPaginate(20);
|
|
299
|
+
|
|
300
|
+
// ✅ Standard pagination (OK for admin panels)
|
|
301
|
+
$leads = Lead::query()->paginate(20);
|
|
302
|
+
|
|
303
|
+
// ❌ NEVER manual offset on large tables
|
|
304
|
+
Lead::query()->offset(100000)->limit(20)->get();
|
|
305
|
+
// Full scan of 100,000 rows just to skip them!
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Count Optimization
|
|
309
|
+
|
|
310
|
+
```php
|
|
311
|
+
// ❌ SLOW on large tables
|
|
312
|
+
$total = Lead::count(); // Full table scan
|
|
313
|
+
|
|
314
|
+
// ✅ Approximate count (MariaDB)
|
|
315
|
+
$total = DB::selectOne("SELECT TABLE_ROWS FROM information_schema.TABLES WHERE TABLE_NAME = 'leads'")->TABLE_ROWS;
|
|
316
|
+
|
|
317
|
+
// ✅ Exact count with cache
|
|
318
|
+
$total = Cache::remember("leads:count:{$userId}", 60, function () use ($userId) {
|
|
319
|
+
return Lead::where('user_id', $userId)->count();
|
|
320
|
+
});
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
## Model Casts (Strict Types)
|
|
324
|
+
|
|
325
|
+
```php
|
|
326
|
+
class Lead extends Model
|
|
327
|
+
{
|
|
328
|
+
protected $casts = [
|
|
329
|
+
'metadata' => 'array', // JSON → array (auto encode/decode)
|
|
330
|
+
'price' => 'decimal:2', // Always 2 decimal places
|
|
331
|
+
'is_active' => 'boolean', // 1/0 → true/false
|
|
332
|
+
'converted_at' => 'immutable_datetime', // Carbon Immutable (Octane-safe)
|
|
333
|
+
'impressions' => 'integer', // String → int
|
|
334
|
+
'status' => LeadStatus::class, // Backed enum
|
|
335
|
+
];
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
// ✅ Backed enums for status columns
|
|
339
|
+
enum LeadStatus: string
|
|
340
|
+
{
|
|
341
|
+
case Pending = 'pending';
|
|
342
|
+
case Active = 'active';
|
|
343
|
+
case Converted = 'converted';
|
|
344
|
+
case Rejected = 'rejected';
|
|
345
|
+
}
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
## Health Check
|
|
349
|
+
|
|
350
|
+
```php
|
|
351
|
+
// routes/web.php — Octane worker health
|
|
352
|
+
Route::get('/health', function () {
|
|
353
|
+
try {
|
|
354
|
+
DB::connection()->getPdo();
|
|
355
|
+
$dbOk = true;
|
|
356
|
+
} catch (\Exception $e) {
|
|
357
|
+
DB::reconnect();
|
|
358
|
+
$dbOk = false;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
return response()->json([
|
|
362
|
+
'status' => $dbOk ? 'healthy' : 'degraded',
|
|
363
|
+
'db' => $dbOk,
|
|
364
|
+
'worker_memory' => memory_get_usage(true) / 1024 / 1024 . ' MB',
|
|
365
|
+
'worker_peak' => memory_get_peak_usage(true) / 1024 / 1024 . ' MB',
|
|
366
|
+
], $dbOk ? 200 : 503);
|
|
367
|
+
});
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
## FORBIDDEN
|
|
371
|
+
|
|
372
|
+
| ❌ Don't | ✅ Do |
|
|
373
|
+
|---|---|
|
|
374
|
+
| `strict => false` | `strict => true` + SQL modes |
|
|
375
|
+
| `$table->string('name')` (no length) | `$table->string('name', 255)` |
|
|
376
|
+
| `Lead::all()` in Octane | `Lead::query()->paginate()` or `chunkById()` |
|
|
377
|
+
| Uncaught exception in transaction | `DB::transaction()` closure or explicit rollBack |
|
|
378
|
+
| `$_GET`, `$_POST` | `$request->input()` |
|
|
379
|
+
| `static $cache = []` | Instance property or Redis cache |
|
|
380
|
+
| `offset()` on large tables | `cursorPaginate()` |
|
|
381
|
+
| `migrate:fresh`, `db:wipe` | Incremental migrations only |
|
|
382
|
+
| No index on WHERE/ORDER columns | Composite indexes matching query patterns |
|
|
383
|
+
| `Lead::count()` on millions of rows | Cached count or approximate count |
|
|
384
|
+
| `'metadata' => 'json'` cast | `'metadata' => 'array'` (auto decode) |
|
|
385
|
+
| `datetime` cast | `immutable_datetime` (Octane-safe, no mutation) |
|