Structure.php — Kirki – Freeform Page Builder, Website Builder & Customizer 6.0.13

kirki / libraries / framework / Database / Schema / Structure.php

kirki / libraries / framework / Database / Schema Last commit date

Definitions 3 weeks ago Compiler.php 3 weeks ago SchemaManager.php 3 weeks ago Structure.php 3 weeks ago

Structure.php

740 lines

1	<?php
2
3	/**
4	* Fluent builder for defining database table columns, indexes, and constraints.
5	* Collects column definitions and table-level commands before handing them to the schema compiler.
6	* Provides a chainable API for migrations and programmatic schema changes.
7	*
8	* @package Framework
9	* @subpackage Database\Schema
10	* @since 1.0.0
11	*/
12	namespace Kirki\Framework\Database\Schema;
13
14	\defined('ABSPATH') \|\| exit;
15	use Kirki\Framework\Database\Constants\ColumnTypes;
16	use Kirki\Framework\Database\Connection\Connection;
17	use Kirki\Framework\Database\Schema\Definitions\Definition;
18	use Kirki\Framework\Database\Schema\Definitions\ForeignKeyDefinition;
19	use Exception;
20	class Structure
21	{
22	/**
23	* The name of the table (without prefix).
24	*
25	* @var string\|null
26	*
27	* @since 1.0.0
28	*/
29	protected $table = null;
30	/**
31	* The database connection instance.
32	*
33	* @var Connection
34	*
35	* @since 1.0.0
36	*/
37	protected $connection = null;
38	/**
39	* The table prefix.
40	*
41	* @var string
42	*
43	* @since 1.0.0
44	*/
45	protected $prefix = '';
46	/**
47	* The columns defined for the table.
48	*
49	* @var array<string,
50	*
51	* @since 1.0.0
52	*/
53	protected $columns = [];
54	/**
55	* The storage engine for the table.
56	*
57	* @var string\|null
58	*
59	* @since 1.0.0
60	*/
61	protected $engine = null;
62	/**
63	* The character set for the table.
64	*
65	* @var string\|null
66	*
67	* @since 1.0.0
68	*/
69	protected $charset = null;
70	/**
71	* The collation for the table.
72	*
73	* @var string\|null
74	*
75	* @since 1.0.0
76	*/
77	protected $collate = null;
78	/**
79	* The commands for the table structure.
80	*
81	* @var array
82	*
83	* @since 1.0.0
84	*/
85	protected $commands = [];
86	/**
87	* Structure constructor.
88	*
89	* @param string $table The table name (without prefix)
90	* @param Connection $connection The database connection instance
91	*
92	* @return void
93	*
94	* @since 1.0.0
95	*/
96	public function __construct(string $table, Connection $connection)
97	{
98	$this->table = $table;
99	$this->connection = $connection;
100	$db = $this->connection->get_db();
101	$this->prefix = $db->prefix;
102	$this->engine = 'InnoDB';
103	$this->charset = $db->charset;
104	$this->collate = $db->collate;
105	}
106	/**
107	* Expose the connection instance.
108	*
109	* @return Connection
110	*
111	* @since 1.0.0
112	*/
113	public function connection()
114	{
115	return $this->connection;
116	}
117	/**
118	* Get the full table name with prefix.
119	*
120	* @return string
121	*
122	* @since 1.0.0
123	*/
124	public function get_table()
125	{
126	return $this->table;
127	}
128	/**
129	* Wrap the table name with the query compiler.
130	*
131	* @param string $table The table name
132	*
133	* @return string
134	*
135	* @since 1.0.0
136	*/
137	public function wrap_table($table)
138	{
139	return $this->connection()->get_query_compiler()->wrap_table($table);
140	}
141	/**
142	* Get the character set for the table.
143	*
144	* @return string\|null
145	*
146	* @since 1.0.0
147	*/
148	public function get_charset()
149	{
150	return $this->charset;
151	}
152	/**
153	* Get the storage engine for the table.
154	*
155	* @return string\|null
156	*
157	* @since 1.0.0
158	*/
159	public function get_engine()
160	{
161	return $this->engine;
162	}
163	/**
164	* Get the collation for the table.
165	*
166	* @return string\|null
167	*
168	* @since 1.0.0
169	*/
170	public function get_collate()
171	{
172	return $this->collate;
173	}
174	/**
175	* Get the commands for the table structure.
176	*
177	* @return array
178	*
179	* @since 1.0.0
180	*/
181	public function get_commands()
182	{
183	return $this->commands;
184	}
185	/**
186	* Set the storage engine for the table.
187	*
188	* @param string $engine The engine name (e.g., 'InnoDB', 'MyISAM')
189	*
190	* @return void
191	*
192	* @throws \Exception
193	*
194	* @since 1.0.0
195	*/
196	public function engine(string $engine)
197	{
198	$available_engines = ['InnoDB', 'MyISAM'];
199	if (!\in_array($engine, $available_engines)) {
200	throw new Exception("Invalid engine: {$engine}");
201	}
202	$this->engine = $engine;
203	}
204	/**
205	* Set the character set for the table.
206	*
207	* @param string $charset The charset (e.g., 'utf8mb4', 'utf8')
208	*
209	* @return void
210	*
211	* @since 1.0.0
212	*/
213	public function charset(string $charset)
214	{
215	$this->charset = $charset;
216	}
217	/**
218	* Set the collation for the table.
219	*
220	* @param string $collate The collation (e.g., 'utf8mb4_unicode_ci', 'utf8_general_ci')
221	*
222	* @return void
223	*
224	* @since 1.0.0
225	*/
226	public function collate(string $collate)
227	{
228	$this->collate = $collate;
229	}
230	/**
231	* Get the columns defined for the table.
232	*
233	* @return array<string, Definition>
234	*
235	* @since 1.0.0
236	*/
237	public function get_columns()
238	{
239	return $this->columns;
240	}
241	/**
242	* Add an auto-incrementing BIGINT primary key column named 'ID'.
243	*
244	* @param string $name The name.
245	*
246	* @return Definition
247	*
248	* @since 1.0.0
249	*/
250	public function id(string $name = 'id')
251	{
252	return $this->big_increment($name)->primary();
253	}
254	/**
255	* Add a TIMESTAMP column.
256	*
257	* @param string $name The column name
258	* @param int $precision The precision for the timestamp
259	*
260	* @return Definition
261	*
262	* @since 1.0.0
263	*/
264	public function timestamp(string $name, $precision = 0)
265	{
266	return $this->add_column(ColumnTypes::TIMESTAMP, $name, \compact('precision'));
267	}
268	/**
269	* Add 'created_at' and 'updated_at' timestamp columns.
270	*
271	* @param int $precision The precision for the timestamp columns
272	*
273	* @return void
274	*
275	* @since 1.0.0
276	*/
277	public function timestamps($precision = 0)
278	{
279	$this->timestamp('created_at', $precision)->use_current();
280	$this->timestamp('updated_at', $precision)->nullable();
281	}
282	/**
283	* Add an INTEGER column.
284	*
285	* @param string $name The column name
286	* @param bool $auto_increment Whether the column is auto-increment
287	* @param bool $unsigned Whether the column is unsigned
288	*
289	* @return Definition
290	*
291	* @since 1.0.0
292	*/
293	public function integer(string $name, $auto_increment = \false, $unsigned = \false)
294	{
295	return $this->add_column(ColumnTypes::INTEGER, $name, \compact('auto_increment', 'unsigned'));
296	}
297	/**
298	* Add a TINYINT column.
299	*
300	* @param string $name The column name
301	* @param bool $auto_increment Whether the column is auto-increment
302	* @param bool $unsigned Whether the column is unsigned
303	*
304	* @return Definition
305	*
306	* @since 1.0.0
307	*/
308	public function tiny_integer(string $name, $auto_increment = \false, $unsigned = \false)
309	{
310	return $this->add_column(ColumnTypes::TINYINT, $name, \compact('auto_increment', 'unsigned'));
311	}
312	/**
313	* Add a BIGINT column.
314	*
315	* @param string $name The column name
316	* @param bool $auto_increment Whether the column is auto-increment
317	* @param bool $unsigned Whether the column is unsigned
318	*
319	* @return Definition
320	*
321	* @since 1.0.0
322	*/
323	public function big_integer(string $name, $auto_increment = \false, $unsigned = \false)
324	{
325	return $this->add_column(ColumnTypes::BIGINT, $name, \compact('auto_increment', 'unsigned'));
326	}
327	/**
328	* Add an unsigned BIGINT column.
329	*
330	* @param string $name The column name
331	* @param bool $auto_increment Whether the column is auto-increment
332	*
333	* @return Definition
334	*
335	* @since 1.0.0
336	*/
337	public function unsigned_big_integer(string $name, $auto_increment = \false)
338	{
339	return $this->big_integer($name, $auto_increment, \true);
340	}
341	/**
342	* Add an unsigned INTEGER column.
343	*
344	* @param string $name The column name
345	* @param bool $auto_increment Whether the column is auto-increment
346	*
347	* @return Definition
348	*
349	* @since 1.0.0
350	*/
351	public function unsigned_integer(string $name, $auto_increment = \false)
352	{
353	return $this->integer($name, $auto_increment, \true);
354	}
355	/**
356	* Add an unsigned TINYINT column.
357	*
358	* @param string $name The column name
359	* @param bool $auto_increment Whether the column is auto-increment
360	*
361	* @return Definition
362	*
363	* @since 1.0.0
364	*/
365	public function unsigned_tiny_integer(string $name, $auto_increment = \false)
366	{
367	return $this->tiny_integer($name, $auto_increment, \true);
368	}
369	/**
370	* Add an auto-incrementing unsigned INTEGER column.
371	*
372	* @param string $name The column name
373	*
374	* @return Definition
375	*
376	* @since 1.0.0
377	*/
378	public function increment(string $name)
379	{
380	return $this->unsigned_integer($name, \true);
381	}
382	/**
383	* Add an auto-incrementing unsigned BIGINT column.
384	*
385	* @param string $name The column name
386	*
387	* @return Definition
388	*
389	* @since 1.0.0
390	*/
391	public function big_increment(string $name)
392	{
393	return $this->unsigned_big_integer($name, \true);
394	}
395	/**
396	* Add a DECIMAL column.
397	*
398	* @param string $name The column name
399	* @param int $total The total number of digits
400	* @param int $places The number of decimal places
401	*
402	* @return Definition
403	*
404	* @since 1.0.0
405	*/
406	public function decimal(string $name, $total = 8, $places = 2)
407	{
408	return $this->add_column(ColumnTypes::DECIMAL, $name, \compact('total', 'places'));
409	}
410	/**
411	* Add a TEXT column.
412	*
413	* @param string $name The column name
414	*
415	* @return Definition
416	*
417	* @since 1.0.0
418	*/
419	public function text(string $name)
420	{
421	return $this->add_column(ColumnTypes::TEXT, $name);
422	}
423	/**
424	* Add a STRING (VARCHAR) column.
425	*
426	* @param string $name The column name
427	* @param int\|null $length The length of the string
428	*
429	* @return Definition
430	*
431	* @since 1.0.0
432	*/
433	public function string(string $name, $length = null)
434	{
435	$length = $length ?: 255;
436	return $this->add_column(ColumnTypes::STRING, $name, \compact('length'));
437	}
438	/**
439	* Add a MEDIUM TEXT column.
440	*
441	* @param string $name The column name
442	*
443	* @return Definition
444	*
445	* @since 1.0.0
446	*/
447	public function medium_text(string $name)
448	{
449	return $this->add_column(ColumnTypes::MEDIUM_TEXT, $name);
450	}
451	/**
452	* Add a LONG TEXT column.
453	*
454	* @param string $name The column name
455	*
456	* @return Definition
457	*
458	* @since 1.0.0
459	*/
460	public function long_text(string $name)
461	{
462	return $this->add_column(ColumnTypes::LONG_TEXT, $name);
463	}
464	/**
465	* Add a BOOLEAN column.
466	*
467	* @param string $name The column name
468	*
469	* @return Definition
470	*
471	* @since 1.0.0
472	*/
473	public function boolean(string $name)
474	{
475	return $this->add_column(ColumnTypes::BOOLEAN, $name);
476	}
477	/**
478	* Add a FLOAT column.
479	*
480	* @param string $name The column name
481	* @param int $precision The precision for the float
482	*
483	* @return Definition
484	*
485	* @since 1.0.0
486	*/
487	public function float(string $name, $precision = 53)
488	{
489	return $this->add_column(ColumnTypes::FLOAT, $name, \compact('precision'));
490	}
491	/**
492	* Add a DOUBLE column.
493	*
494	* @param string $name The column name
495	*
496	* @return Definition
497	*
498	* @since 1.0.0
499	*/
500	public function double(string $name)
501	{
502	return $this->add_column(ColumnTypes::DOUBLE, $name);
503	}
504	/**
505	* Add a DATE column.
506	*
507	* @param string $name The column name
508	*
509	* @return Definition
510	*
511	* @since 1.0.0
512	*/
513	public function date(string $name)
514	{
515	return $this->add_column(ColumnTypes::DATE, $name);
516	}
517	/**
518	* Add a DATETIME column.
519	*
520	* @param string $name The column name
521	* @param int $precision The precision for the datetime
522	*
523	* @return Definition
524	*
525	* @since 1.0.0
526	*/
527	public function datetime(string $name, $precision = 0)
528	{
529	return $this->add_column(ColumnTypes::DATETIME, $name, \compact('precision'));
530	}
531	/**
532	* Add a TIME column.
533	*
534	* @param string $name The column name
535	* @param int $precision The precision for the time
536	*
537	* @return Definition
538	*
539	* @since 1.0.0
540	*/
541	public function time(string $name, $precision = 0)
542	{
543	return $this->add_column(ColumnTypes::TIME, $name, \compact('precision'));
544	}
545	/**
546	* Add an ENUM column.
547	*
548	* @param string $name The column name
549	* @param array $values The values for the enum
550	*
551	* @return Definition
552	*
553	* @since 1.0.0
554	*/
555	public function enum(string $name, array $values)
556	{
557	return $this->add_column(ColumnTypes::ENUM, $name, \compact('values'));
558	}
559	/**
560	* Add a SET column.
561	*
562	* @param string $name The column name
563	* @param array $values The values for the set
564	*
565	* @return Definition
566	*
567	* @since 1.0.0
568	*/
569	public function set(string $name, array $values)
570	{
571	return $this->add_column(ColumnTypes::SET, $name, \compact('values'));
572	}
573	/**
574	* Add an IP address column.
575	*
576	* @param string $name The column name
577	*
578	* @return Definition
579	*
580	* @since 1.0.0
581	*/
582	public function ip_address(string $name)
583	{
584	return $this->add_column(ColumnTypes::IP_ADDRESS, $name);
585	}
586	/**
587	* Add a UUID column.
588	*
589	* @param string $name The column name
590	*
591	* @return Definition
592	*
593	* @since 1.0.0
594	*/
595	public function uuid(string $name)
596	{
597	return $this->add_column(ColumnTypes::UUID, $name);
598	}
599	/**
600	* Add a YEAR column.
601	*
602	* @param string $name The column name
603	*
604	* @return Definition
605	*
606	* @since 1.0.0
607	*/
608	public function year(string $name)
609	{
610	return $this->add_column(ColumnTypes::YEAR, $name);
611	}
612	/**
613	* Add a column definition to the table.
614	*
615	* @param string $type The column type
616	* @param string $name The column name
617	* @param array $parameters Additional parameters for the column
618	*
619	* @return Definition
620	*
621	* @since 1.0.0
622	*/
623	protected function add_column($type, $name, array $parameters = [])
624	{
625	return $this->add_column_definition(new Definition(\array_merge(\compact('type', 'name'), $parameters)));
626	}
627	/**
628	* Add a column definition object to the columns array.
629	*
630	* @param Definition $definition The column definition
631	*
632	* @return Definition
633	*
634	* @since 1.0.0
635	*/
636	protected function add_column_definition(Definition $definition)
637	{
638	$this->columns[] = $definition;
639	return $definition;
640	}
641	/**
642	* Define the primary key for the table.
643	*
644	* @param string\|array $keys The column(s) to use as primary key
645	* @param string\|null $key_name Optional constraint name
646	*
647	* @return $this
648	*
649	* @since 1.0.0
650	*/
651	public function primary($keys, $key_name = null)
652	{
653	if (!\is_array($keys)) {
654	$keys = [$keys];
655	}
656	$this->commands['primary'] = ['name' => $key_name, 'keys' => $keys];
657	return $this;
658	}
659	/**
660	* Define a unique key for the table.
661	*
662	* @param string\|array $keys The column(s) to use as unique key
663	* @param string\|null $key_name Optional constraint name
664	*
665	* @return $this
666	*
667	* @since 1.0.0
668	*/
669	public function unique($keys, $key_name = null)
670	{
671	if (!\is_array($keys)) {
672	$keys = [$keys];
673	}
674	if (empty($key_name)) {
675	$key_name = \sprintf('%s_%s_unique', $this->get_table(), \implode('_', $keys));
676	}
677	$this->commands['unique'][] = ['name' => $key_name, 'keys' => $keys];
678	return $this;
679	}
680	/**
681	* Define an index for the table.
682	*
683	* @param string\|array $keys The column(s) to index
684	* @param string\|null $key_name Optional index name
685	*
686	* @return $this
687	*
688	* @since 1.0.0
689	*/
690	public function index($keys, $key_name = null)
691	{
692	if (!\is_array($keys)) {
693	$keys = [$keys];
694	}
695	if (empty($key_name)) {
696	$key_name = \sprintf('%s_%s_index', $this->get_table(), \implode('_', $keys));
697	}
698	$this->commands['index'][] = ['name' => $key_name, 'keys' => $keys];
699	return $this;
700	}
701	/**
702	* Define a foreign key constraint.
703	*
704	* @param string $column The column.
705	* @param mixed $name The name.
706	*
707	* @return ForeignKeyDefinition
708	*
709	* @since 1.0.0
710	*/
711	public function foreign(string $column, $name = null)
712	{
713	$command = new ForeignKeyDefinition(\compact('column', 'name'));
714	$this->commands['foreign'][] = $command;
715	return $command;
716	}
717	/**
718	* Get the compiler instance for compiling table structure.
719	*
720	* @return Compiler
721	*
722	* @since 1.0.0
723	*/
724	protected function compiler()
725	{
726	return new Compiler($this->connection);
727	}
728	/**
729	* Get the complete SQL statement for creating the table.
730	*
731	* @return string
732	*
733	* @since 1.0.0
734	*/
735	public function get_table_structure()
736	{
737	return $this->compiler()->compile_create($this);
738	}
739	}
740