cartflows / docs / wiki / Environment-Configuration.md

Environment-Configuration.md in CartFlows – Funnel Builder & Checkout Plugin for WooCommerce 3.0.1, at docs/wiki/Environment-Configuration.md

186 lines 4.5 KB

Raw Download Zip

1	# Environment Configuration
2
3	CartFlows uses `@wordpress/env` (wp-env) to provide an isolated Docker-based WordPress environment for local development and E2E testing.
4
5	## Prerequisites
6
7	\| Tool \| Purpose \|
8	\|------\|---------\|
9	\| Docker Desktop \| Runs the WordPress containers \|
10	\| Node.js + npm \| Manages wp-env and JavaScript dependencies \|
11	\| Composer \| Manages PHP dependencies \|
12	\| PHP 7.2+ \| Required for running PHP unit tests locally \|
13
14	## wp-env Setup
15
16	wp-env creates two separate WordPress environments in Docker:
17
18	\| Environment \| Port \| Purpose \|
19	\|-------------\|------\|---------\|
20	\| Development \| `http://localhost:8888` \| Local dev environment \|
21	\| Tests \| `http://localhost:8889` \| E2E test environment \|
22
23	### Start the environment
24
25	```bash
26	npm run env:start
27	```
28
29	This:
30	1. Pulls WordPress and MySQL Docker images
31	2. Starts the containers
32	3. Installs and activates the CartFlows plugin
33	4. Sets up the test environment on port 8889
34
35	### Stop the environment
36
37	```bash
38	npm run env:stop
39	```
40
41	### Reset to clean state
42
43	```bash
44	# Reset database but keep Docker images
45	npm run env:clean
46
47	# Destroy everything (containers + volumes)
48	npm run env:destroy
49	```
50
51	After `env:destroy`, you need to run `env:start` again to recreate the environment.
52
53	## wp-env Configuration
54
55	wp-env is configured via `.wp-env.json` in the project root (if present). A typical configuration for CartFlows:
56
57	```json
58	{
59	"core": null,
60	"plugins": [ "." ],
61	"themes": [],
62	"port": 8888,
63	"testsPort": 8889,
64	"config": {
65	"WP_DEBUG": true,
66	"WP_DEBUG_LOG": true,
67	"SCRIPT_DEBUG": true
68	}
69	}
70	```
71
72	\| Config Key \| Description \|
73	\|------------\|-------------\|
74	\| `core` \| WordPress version (`null` = latest) \|
75	\| `plugins` \| `"."` includes CartFlows itself \|
76	\| `port` \| Development environment port \|
77	\| `testsPort` \| Test environment port \|
78	\| `WP_DEBUG` \| Enable WordPress debug mode \|
79	\| `WP_DEBUG_LOG` \| Log errors to `wp-content/debug.log` \|
80	\| `SCRIPT_DEBUG` \| Use unminified scripts \|
81
82	## Development Workflow
83
84	```bash
85	# 1. Install dependencies
86	composer install
87	npm install
88
89	# 2. Start WordPress environment
90	npm run env:start
91
92	# 3. Build React apps (watch mode for development)
93	npm run start
94
95	# 4. Open the development site
96	# → http://localhost:8888/wp-admin
97	# → Username: admin \| Password: password (wp-env defaults)
98
99	# 5. Run tests
100	composer test
101	npm run test:e2e
102	```
103
104	## Manual WordPress Installation
105
106	If you prefer not to use wp-env, CartFlows can be developed in any WordPress environment:
107
108	1. Install WordPress locally (MAMP, LocalWP, Laragon, WP-CLI, etc.)
109	2. Install and activate WooCommerce
110	3. Clone CartFlows into `wp-content/plugins/cartflows/`
111	4. Run `composer install` in the plugin directory
112	5. Run `npm install && npm run build`
113	6. Activate the CartFlows plugin in WordPress admin
114
115	## Required WordPress Settings for Development
116
117	\| Setting \| Value \| Reason \|
118	\|---------\|-------\|--------\|
119	\| `WP_DEBUG` \| `true` \| Show PHP errors \|
120	\| `WP_DEBUG_LOG` \| `true` \| Log to `debug.log` \|
121	\| `SCRIPT_DEBUG` \| `true` \| Use unminified scripts \|
122	\| Permalink structure \| Post name \| Required for CartFlows URLs \|
123
124	Set these in `wp-config.php`:
125
126	```php
127	define( 'WP_DEBUG', true );
128	define( 'WP_DEBUG_LOG', true );
129	define( 'SCRIPT_DEBUG', true );
130	```
131
132	## Required Plugins
133
134	CartFlows requires WooCommerce. For full feature development, also install:
135	- WooCommerce (required)
136	- Any page builder you're developing for (Elementor, Beaver Builder, etc.)
137
138	## PHP Configuration
139
140	Recommended `php.ini` settings for development:
141
142	```ini
143	max_execution_time = 120
144	memory_limit = 256M
145	upload_max_filesize = 64M
146	post_max_size = 64M
147	```
148
149	## Assets in Development
150
151	For React development with hot-reloading:
152
153	```bash
154	npm run start # Webpack watch mode — rebuilds on file change
155	```
156
157	This rebuilds `editor-app.js` and `settings-app.js` automatically when source files change. You must still reload the WordPress admin page to see changes.
158
159	Note: `npm run start` produces development (unminified) builds. Always run `npm run build` before committing.
160
161	## Environment Variables
162
163	CartFlows does not use `.env` files — all configuration is managed through WordPress's `wp-config.php` and plugin settings UI.
164
165	## Cleaning Up
166
167	```bash
168	# Remove build artifacts (not committed to git)
169	rm -rf admin-core/assets/build/*.js.map
170
171	# Remove PHP vendor directory (can be regenerated)
172	rm -rf vendor/
173	composer install
174
175	# Remove node_modules (can be regenerated)
176	rm -rf node_modules/
177	npm install
178	```
179
180	## Related Pages
181
182	- [](Getting-StartedGetting-Started](Getting-Started](Getting-Started)
183	- [](Testing-GuideTesting-Guide](Testing-Guide](Testing-Guide)
184	- [](Build-SystemBuild-System](Build-System](Build-System)
185	- [](Contributing-GuideContributing-Guide](Contributing-Guide](Contributing-Guide)
186