ivyforms / DEVELOPER.md

DEVELOPER.md in The Innovative Form Builder – IvyForms 0.6, at DEVELOPER.md

234 lines 7.4 KB

Raw Download Zip

1	# IvyForms Developer Documentation
2
3	This document provides technical information for developers who want to contribute to or understand the IvyForms WordPress plugin.
4
5	## Project Overview
6
7	IvyForms is a modern form builder for WordPress built with PHP 7.4+ on the backend and Vue.js/TypeScript on the frontend. The plugin uses a component-based architecture and dependency injection to maintain clean code.
8
9	## Project Structure
10
11	```
12	ivyforms/
13	└── backend/
14	└── src/
15	├── Config/
16	├── Common/
17	│ ├── Exceptions/
18	│ └── Sanitizer/
19	├── Controllers/
20	├── Entity/
21	├── Factory/
22	├── Repository/
23	├── Routes/
24	├── Services/
25	└── ValueObjects/
26	├── vendor/
27	├── composer.json
28	├── composer.lock
29	├── phpcs.xml
30	├── phpmd-ruleset.xml
31	├── phpstan.neon
32	└── frontend/
33	├── src/
34	├── dist/
35	├── node_modules/
36	├── languages/
37	├── view/
38	├── backend/
39	└── frontend/
40	```
41
42	### Directories Explanation
43
44	- backend/: Contains the PHP backend code and dependencies.
45	- src/: Source code for the backend.
46	- Config/: Contains configuration files for the application
47	- Common/: Contains common files such as exceptions and helper classes
48	- Exceptions/: Custom exception classes.
49	- Sanitizer/: Contains class for sanitizing data.
50	- Controllers/: Handle HTTP requests and responses. They use services to process the business logic
51	- Entity/: Represent the core data structures of the application.
52	- Factory/: Responsible for creating instances of entities or other objects.
53	- Repository/: Handle data persistence and retrieval, typically interacting with a database.
54	- Routes/: Define the application's routes and map them to controller actions.
55	- Services/: Contain the business logic of the application.
56	- ValueObjects/: Represent immutable values that describe certain aspects of the domain.
57
58	- frontend/: Contains the frontend code and dependencies.
59	- src/: Source code for the frontend.
60	- dist/: Compiled and bundled frontend assets.
61	- node_modules/: npm dependencies.
62	- Various configuration files for TypeScript, ESLint, and build tools.
63
64	- view/: Contains view templates.
65	- backend/: Backend view files.
66	- frontend/: Frontend view files.
67	- languages/: Contains language files for localization.
68
69	## Development Environment Setup
70
71	### Requirements
72
73	- PHP 7.4 or higher
74	- WordPress 5.0 or higher
75	- Node.js 14.0 or higher
76	- Composer 2.0 or higher
77	- npm 6.0 or higher
78
79	### Backend Setup
80	1. Navigate to the backend directory:
81	```bash
82	cd backend
83	```
84
85	2. Install PHP dependencies:
86	```bash
87	composer install
88	```
89
90	3. Run PHP code quality tools:
91	```bash
92	# Run PHP Code Sniffer
93	backend/vendor/bin/phpcs --standard=PSR12 backend/src
94
95	# Run PHPStan (Level 6)
96	backend/vendor/bin/phpstan analyse -c backend/phpstan.neon -l 6 backend/src --memory-limit=-1
97
98	# Run PHP Mess Detector:
99	backend/vendor/bin/phpmd backend/src ansi backend/phpmd-ruleset.xml
100	```
101
102	### Frontend Setup
103
104	1. Navigate to the frontend directory:
105	```bash
106	cd frontend
107	```
108
109	2. Install NPM dependencies:
110	```bash
111	npm install --force
112	```
113
114	3. Start development server:
115	```bash
116	npm run dev
117	```
118
119	4. Build for production:
120	```bash
121	npm run build
122	```
123
124	5. Run code quality tools:
125	```bash
126	# Run ESLint
127	npm run lint
128
129	# Run TypeScript type checking
130	npm run type-check
131
132	# Run formatting checks
133	npm run format
134	```
135
136	## Build Process
137
138	The plugin uses modern build tools to optimize the production code:
139
140	### Frontend Build Process
141
142	- Development: During development, Vite provides a fast development server with Hot Module Replacement (HMR).
143	- Production: For production, frontend assets are compiled and minified using Vite's build process.
144
145	The frontend is built using:
146	- Vue.js 3: Progressive JavaScript framework
147	- TypeScript: Typed JavaScript for better development experience
148	- Vite: Build tool for modern web projects
149	- Pinia/Vuex: State management
150	- ESLint: JavaScript/TypeScript linting
151
152	### Backend Build Process
153
154	The backend is managed using:
155	- Composer: PHP dependency management
156	- PHP_CodeSniffer: Code style checking
157	- PHPStan: Static analysis tool
158	- PHP Mess Detector: Code quality tool
159	- PHP Dependency Injection (DI) for managing dependencies
160
161	## External Libraries & Services
162
163	### JavaScript Libraries
164
165	The compiled files in `frontend/dist/` are built from source code in the `frontend/src/` directory. The build process uses npm and Vite to compile Vue.js components, TypeScript files, and other assets.
166
167	### External Services
168
169	The plugin uses the following external services:
170
171	1. ipwho.is API: Used to auto-detect user's country code for phone number input fields.
172	- Implementation: Used in the phone number component to improve UX by pre-selecting the user's country code.
173
174	## Coding Standards
175
176	### PHP Coding Standards
177
178	We follow the WordPress PHP Coding Standards with some modifications:
179	- PSR-4 autoloading
180	- PSR-12 code style
181	- Type hints and return types
182
183	### JavaScript/TypeScript Coding Standards
184
185	- Vue.js Style Guide (Priority A & B rules)
186	- AirBnB JavaScript Style Guide with TypeScript extensions
187	- Component names in PascalCase
188	- Props in camelCase
189
190	### SCSS/CSS (BEM) Guidelines
191
192	Adopt BEM (Block–Element–Modifier) for predictable, reusable, and low-specificity styles in SCSS.
193
194	- Naming
195	- Block: `.component` (semantic, standalone piece of UI)
196	- Element: `.component__element` (a part of a block that has no standalone meaning)
197	- Modifier: `.component--modifier` or `.component__element--modifier` (a variant/state)
198	- State helpers (transient/JS-driven): `.is-active`, `.is-open`, `.has-error`
199	- Rules
200	- Modifiers are never used alone; always together with their base block/element
201	- Keep specificity low: avoid IDs and tag selectors, prefer classes
202	- Keep selectors flat: no chaining like `.block .other-block`; communicate via classes
203	- SCSS nesting depth: max 2 levels inside a block (elements/modifiers only)
204	- Scope third‑party selectors (e.g., Element Plus `.el-*`) under a block wrapper
205	- Prefer utility classes for spacing/layout (e.g., `ivyforms-flex`, `ivyforms-p-4`)
206	- Use design tokens/CSS variables (`var(--map-...)`) instead of hard-coded values
207	- File organization
208	- Co-locate styles with the component (SFC `<style lang="scss">` or a matching SCSS file)
209	- One block per component when possible; use clear, page-scoped blocks like `.ivyforms-all-entries`
210
211	## Debugging
212
213	### PHP Debugging
214
215	The plugin uses WordPress's built-in debugging tools:
216	- Set `WP_DEBUG` to `true` in your `wp-config.php` file
217	- Use `error_log()` for logging
218	- update IVYFORMS_DEV constant to `true` in `ivyforms.php` for development mode
219
220	### JavaScript Debugging
221
222	- Vue.js DevTools browser extension for Vue component debugging
223	- Console logging with `console.log()`, `console.error()`, etc.
224
225	## Source Code & Compilation
226
227	The minified JavaScript and CSS files in `frontend/dist/` directory are compiled from source code in the `frontend/src/` directory. The full source code is available in the plugin repository.
228
229	To modify the frontend code, edit the files in `frontend/src/` and run the build process to update the compiled assets.
230
231	## License
232
233	This project is licensed under the GPL v2 or later.
234