defender-security / extra / hub-connector / README.md

README.md in Defender Security – Malware Scanner, Login Security & Firewall 6.2.2, at extra/hub-connector/README.md

171 lines 6.7 KB

Raw Download Zip

1	# Hub Connector #
2
3	Hub Connector module is used in our free plugins to connect the user websites with Hub.
4
5	## Requirements:
6
7	* PHP: 7.4+
8	* WordPress: 5.0+
9
10	# How to use it #
11
12	1. Insert this repository as sub-module into the existing project
13	2. Include the file `connector.php` in your plugin and initialize it by calling ``\WPMUDEV\Hub\Connector::get();``.
14	3. Set the plugin specific options (see below for more details) using a unique plugin identifier. Identifier can be any unique string.
15	``\WPMUDEV\Hub\Connector::get()->set_options( 'blc', $options );``
16	4. Call the action `wpmudev_hub_connector_ui` where you want the Hub connector UI to render.
17	5. [IMPORTANT] Make sure your distributable plugin NOT having these files ( via your build script ):
18	- `test/` ( whole directory)
19	- `pipeline-scipts/` ( whole directory)
20	- `.gitignore`
21	- `bitbucket-pipelines.yml`
22	- `phpcs.ruleset.xml`
23	6. Done!
24
25	### Options
26
27	There are a few plugin specific options you need to set in order for this module to work properly without conflicting with other WPMUDEV plugins.
28
29	These are the accepted options:
30
31	\| Option \| Type \| Sample \| Description \|
32	\|--------------\|-------\|------------------------------------------------------------------------------------\|------------------------------------------------------------------------------------------------------------------------------\|
33	\| `screens` \| Array \| `array( 'toplevel_page_blc' )` \| Array of plugin admin screen IDs. \|
34	\| `extra_args` \| Array \| `array( 'auth' = array( 'ref' => 'blc' ), 'register' => array( 'ref' => 'blc' ) )` \| Extra arguments to be added to the URLs of authentication with WPMUDEV.<br/>See more details about the expected items below. \|
35
36	#### Extra Arguments
37
38	Extra custom arguments can be set to URLs used in Hub Connector auth page. Each sub items should contain array of custom arguments (key and value).
39
40	Expected items:
41
42	\| Key \| Type \| Description \|
43	\|-------------------\|-------\|-----------------------------------------------\|
44	\| `auth` \| Array \| Custom for default login form action URL. \|
45	\| `team_auth` \| Array \| Arguments for team selection form action URL. \|
46	\| `google_auth` \| Array \| Arguments for Google auth form action URL. \|
47	\| `register` \| Array \| Arguments for registration URL. \|
48	\| `forgot_password` \| Array \| Arguments for forgot password URL. \|
49
50
51	## Sample Usage
52
53	Hub connector should be loaded unconditionally on every page load and admin screen should be set. Otherwise some hooks may not work.
54	```
55	<?php
56	// Load base file of Hub Connector.
57	if ( file_exists( \HUB_CONNECTOR_DIR . 'external/hub-connector/connector.php' ) ) {
58	include_once \HUB_CONNECTOR_DIR . 'external/hub-connector/connector.php';
59	// Initialize and set options.
60	\WPMUDEV\Hub\Connector::get()->set_options( 'blc', $options );
61	}
62
63	// Now conditionally render Hub connector UI somewhere in your plugin.
64	if ( $my_condition === true ) {
65	do_action( 'wpmudev_hub_connector_ui', 'blc' );
66	}
67	```
68
69
70
71	## Rendering Hub Connector ##
72
73	```
74	<?php
75	// Render Hub connector UI somewhere in BLC.
76	// Use a unique name to identify your plugin.
77	do_action( 'wpmudev_hub_connector_ui', 'blc' );
78	```
79
80	### Optional: Show the UI only when not connected ##
81
82	```
83	<?php
84	// Show UI only when not logged in.
85	if ( ! \WPMUDEV\Hub\Connector\API::get()->is_logged_in() ) {
86	// Render Hub connector UI.
87	do_action( 'wpmudev_hub_connector_ui', 'blc' );
88	}
89	```
90
91	## Available Helpers ##
92
93	```
94	<?php
95	// Check if website is connected with Hub.
96	$is_logged_in = \WPMUDEV\Hub\Connector\API::get()->is_logged_in();;
97	```
98
99	```
100	<?php
101	// Get the API key.
102	$api_key = \WPMUDEV\Hub\Connector\API::get()->get_api_key();
103	```
104
105	```
106	<?php
107	// Get the current membership type.
108	$membership_type = \WPMUDEV\Hub\Connector\Data::get()->membership_type();
109	```
110
111	```
112	<?php
113	// Get the current member profile data.
114	$profile = \WPMUDEV\Hub\Connector\Data::get()->profile_data();
115	```
116
117	## Modifying texts ##
118
119	You can modify texts in Hub Connector UI using `wpmudev_hub_connector_localize_text_vars` filter.
120
121	```
122	<?php
123	// Modifying login page texts.
124	add_filter( 'wpmudev_hub_connector_localize_text_vars', function ( $texts, $plugin ) {
125	if ( 'blc' === $plugin ) {
126	$texts['login_title'] = 'My custom login title';
127	}
128
129	return $texts;
130	});
131	```
132
133	## Action Hooks ##
134
135	There are a few action hooks which you can use in your plugins.
136
137	\| Hook \| Description \|
138	\|----------------------------------------------\|------------------------------------------------------\|
139	\| `wpmudev_hub_connector_sync_completed` \| Runs after every successful hub sync. \|
140	\| `wpmudev_hub_connector_first_sync_completed` \| Runs after first hub sync after connecting with Hub. \|
141
142	# Development
143
144	Do not commit anything directly to `master` branch. The `master` branch should always be production ready. All plugins will be using it as a submodule.
145
146	## Build Tasks (npm)
147
148	Everything should be handled by npm. Note that you don't need to interact with Gulp in a direct way.
149
150	\| Command \| Action \|
151	\|-------------------\|----------------------------------------------------------\|
152	\| `npm run watch` \| Compiles and watch for changes. \|
153	\| `npm run compile` \| Compile production ready assets. \|
154	\| `npm run build` \| Build production ready submodule inside `/build/` folder \|
155
156	## Git Workflow
157
158	- Create a new branch from `dev` branch: `git checkout -b branch-name`. Try to give it a descriptive name. For example:
159	- `release/X.X.X` for next releases
160	- `new/some-feature` for new features
161	- `enhance/some-enhancement` for enhancements
162	- `fix/some-bug` for bug fixing
163	- Make your commits and push the new branch: `git push -u origin branch-name`
164	- File the new Pull Request against `dev` branch
165	- Assign somebody to review your code.
166	- Once the PR is approved and finished, merge it in `dev` branch.
167	- Checkout `dev` branch.
168	- Run `npm run build` and copy all files and folders from the `build` folder.
169	- Checkout `master` branch (preferably in a different folder) and replace all files and folders with copied content from the `build` folder.
170	- Commit and push the `master` branch changes.
171	- Inform all plugin devs to update the submodule to the latest commit.