ivyforms / DEVELOPER.md

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

233 lines 7.3 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 all backend quality checks
93	make quality
94
95	# Run individual checks
96	make phpcs
97	make phpstan
98	make phpmd
99	```
100
101	### Frontend Setup
102
103	1. Navigate to the frontend directory:
104	```bash
105	cd frontend
106	```
107
108	2. Install NPM dependencies:
109	```bash
110	npm install --force
111	```
112
113	3. Start development server:
114	```bash
115	npm run dev
116	```
117
118	4. Build for production:
119	```bash
120	npm run build
121	```
122
123	5. Run code quality tools:
124	```bash
125	# Run ESLint
126	npm run lint
127
128	# Run TypeScript type checking
129	npm run type-check
130
131	# Run formatting checks
132	npm run format
133	```
134
135	## Build Process
136
137	The plugin uses modern build tools to optimize the production code:
138
139	### Frontend Build Process
140
141	- Development: During development, Vite provides a fast development server with Hot Module Replacement (HMR).
142	- Production: For production, frontend assets are compiled and minified using Vite's build process.
143
144	The frontend is built using:
145	- Vue.js 3: Progressive JavaScript framework
146	- TypeScript: Typed JavaScript for better development experience
147	- Vite: Build tool for modern web projects
148	- Pinia/Vuex: State management
149	- ESLint: JavaScript/TypeScript linting
150
151	### Backend Build Process
152
153	The backend is managed using:
154	- Composer: PHP dependency management
155	- PHP_CodeSniffer: Code style checking
156	- PHPStan: Static analysis tool
157	- PHP Mess Detector: Code quality tool
158	- PHP Dependency Injection (DI) for managing dependencies
159
160	## External Libraries & Services
161
162	### JavaScript Libraries
163
164	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.
165
166	### External Services
167
168	The plugin uses the following external services:
169
170	1. ipwho.is API: Used to auto-detect user's country code for phone number input fields.
171	- Implementation: Used in the phone number component to improve UX by pre-selecting the user's country code.
172
173	## Coding Standards
174
175	### PHP Coding Standards
176
177	We follow the WordPress PHP Coding Standards with some modifications:
178	- PSR-4 autoloading
179	- PSR-12 code style
180	- Type hints and return types
181
182	### JavaScript/TypeScript Coding Standards
183
184	- Vue.js Style Guide (Priority A & B rules)
185	- AirBnB JavaScript Style Guide with TypeScript extensions
186	- Component names in PascalCase
187	- Props in camelCase
188
189	### SCSS/CSS (BEM) Guidelines
190
191	Adopt BEM (Block–Element–Modifier) for predictable, reusable, and low-specificity styles in SCSS.
192
193	- Naming
194	- Block: `.component` (semantic, standalone piece of UI)
195	- Element: `.component__element` (a part of a block that has no standalone meaning)
196	- Modifier: `.component--modifier` or `.component__element--modifier` (a variant/state)
197	- State helpers (transient/JS-driven): `.is-active`, `.is-open`, `.has-error`
198	- Rules
199	- Modifiers are never used alone; always together with their base block/element
200	- Keep specificity low: avoid IDs and tag selectors, prefer classes
201	- Keep selectors flat: no chaining like `.block .other-block`; communicate via classes
202	- SCSS nesting depth: max 2 levels inside a block (elements/modifiers only)
203	- Scope third‑party selectors (e.g., Element Plus `.el-*`) under a block wrapper
204	- Prefer utility classes for spacing/layout (e.g., `ivyforms-flex`, `ivyforms-p-4`)
205	- Use design tokens/CSS variables (`var(--map-...)`) instead of hard-coded values
206	- File organization
207	- Co-locate styles with the component (SFC `<style lang="scss">` or a matching SCSS file)
208	- One block per component when possible; use clear, page-scoped blocks like `.ivyforms-all-entries`
209
210	## Debugging
211
212	### PHP Debugging
213
214	The plugin uses WordPress's built-in debugging tools:
215	- Set `WP_DEBUG` to `true` in your `wp-config.php` file
216	- Use `error_log()` for logging
217	- update IVYFORMS_DEV constant to `true` in `ivyforms.php` for development mode
218
219	### JavaScript Debugging
220
221	- Vue.js DevTools browser extension for Vue component debugging
222	- Console logging with `console.log()`, `console.error()`, etc.
223
224	## Source Code & Compilation
225
226	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.
227
228	To modify the frontend code, edit the files in `frontend/src/` and run the build process to update the compiled assets.
229
230	## License
231
232	This project is licensed under the GPL v2 or later.
233