You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An array with language keywords to avoid using as param or function names, template engine will solve conflicts
49
+
An array with language keywords to avoid using as param or function names, template engine will solve conflicts.
50
50
51
51
**getIdentifierOverrides**
52
-
Returns an associative array that can be used to override keywords with pre-defined word using `overrideIdentifier` filter.
52
+
Returns an associative array that can be used to override keywords with a pre-defined word using `overrideIdentifier` filter.
53
53
54
54
**getFiles**
55
55
An array with a list of language template files in [twig format](https://twig.symfony.com/).
56
56
Each file scope determines what template parameters will be available.
57
57
58
-
* Default scope - Basic SDK and language-specific params (package name, language name, etc…)
59
-
* Service scope - Generate x templates where x is the number of API services, adds service-specific params to the template (service name, methods, etc…)
60
-
* Method scope - Generate x*y templates where x is the number of API services and y is the number of methods, adds service and method-specific params to the template (service name, method name, method params, etc…), good for generating MD files with examples for using each method
61
-
* Copy scope - Static files (like images, etc…) that will just get copied and not processed by twig.
58
+
* Default scope - Basic SDK and language-specific params such as package name and language name.
59
+
* Service scope - Generate x templates where x is the number of API services, adds service-specific params to the template such as service name and methods.
60
+
* Method scope - Generate x*y templates where x is the number of API services and y is the number of methods, adds service and method-specific params to the template, such as service name, method name, and method params. Used to generate MD files with examples for documenting each method.
61
+
* Copy scope - Static files such as imagesthat will be copied directly and not processed by twig.
62
62
63
63
**getTypeName**
64
64
This method receives the API param type and should return the equivalent param in the implemented language.
@@ -67,19 +67,19 @@ This method receives the API param type and should return the equivalent param i
67
67
This method receives the API param and should return the equivalent default value of param in the implemented language, for example, a default array param in PHP is represented as [].
68
68
69
69
**getParamExample**
70
-
This method receives the API param and should return the equivalent example value of param in the implemented language, for example, if an example value is **some text** in PHP return value should be **'some text'** (with quotes).
70
+
This method receives the API param and should return the equivalent example value of param in the implemented language. For example, if an example value is **some text** in PHP, the return value should be **'some text'** (with quotes).
71
71
72
-
Notice: The easiest way to get started is to copy an existing language class close to the new language about to be implemented and just edit it.
72
+
Note: The easiest way to get started is to copy an existing language class close to the new language about to be implemented and just edit it.
73
73
74
74
## Adding Templates
75
75
76
76
Add your new templates as listed in your language class **getFiles** method. Make sure to follow the [checklist](#sdk-checklist) when building the language templates.
77
77
78
-
Make sure to follow the objects structure and service separation architecture. We aim to keep developer experience as consisted as possible across different SDKs to make the learning curve as small as possible.
78
+
Make sure to follow the object's structure and service separation architecture. We aim to keep Appwrite's developer experience as consistent as possible across different SDKs to make the learning curve as flat as possible.
79
79
80
-
> Appwrite SDK generator adds some filters to the TWIG templates to allow common code formatting options like converting text to camelCase, dash-case and other. Full list is available in the [SDK class](https://github.com/appwrite/sdk-generator/blob/master/src/SDK/SDK.php#L62)
80
+
> The Appwrite SDK generator adds some filters to the twig templates to allow common code formatting options like converting text to camelCase, snake_case and others. The full list is available in the [SDK class](https://github.com/appwrite/sdk-generator/blob/master/src/SDK/SDK.php#L62)
81
81
82
-
When in need to test the API templates output, add your new language instance to the `example.php` file like this:
82
+
When you need to test the API templates output, add your new language instance to the `example.php` file like this:
83
83
84
84
sdk-generator/blob/master/example.php:
85
85
@@ -118,16 +118,16 @@ Run the following command (make sure you have an updated docker version on your
118
118
docker run --rm -v $(pwd):/app -w /app php:7.4-cli php example.php
119
119
```
120
120
121
-
>Note: You can just add the new language next to the other languages in example.php file, no need to rewrite the file completely.
121
+
>Note: You can just add the new language next to the other languages in the `example.php` file. You don't need to rewrite the file completely.
122
122
123
-
Check your output files at: /examples/new-lang and make sure the SDK works. When possible add some unit tests.
123
+
Check your output files at: /examples/new-lang and make sure the SDK works. When possible, add some unit tests.
124
124
125
125
## SDK Checklist
126
126
127
-
It is very important for us to create consistent structure, architecture and native like feel for the SDKs we generate.
128
-
In order to accomplish that we have made a checklist of points to support while adding a new language to the SDK generator.
127
+
It is very important for us to create a consistent structure and architecture, as well as a language-native feel for the SDKs we generate.
128
+
To accomplish this, we have made a checklist of points to support while adding a new language to the SDK generator.
129
129
130
-
The following checklist aims to balance consistency among languages, and follow each platform's best practices and coding standards.
130
+
The following checklist aims to balance consistency among languages and follow each platform's best practices and coding standards.
131
131
132
132
-[ ] Proper Coding Standards and Conventions
133
133
-[ ] Proper Skeleton Structure
@@ -142,8 +142,8 @@ The following checklist aims to balance consistency among languages, and follow
142
142
-[ ] Default Headers
143
143
-[ ] 'appwrite-sdk-version' header
144
144
-[ ] Add 'User-Agent' header with device/server name and version + platform name and version (ubuntu-20.04-php-7.0.1 / android-20.0-flutter-3.0)
145
-
-[ ] Add 'origin' header with the following syntax `<scheme>://<identifier>` where scheme is one of `http`, `https`, `appwrite-android`, `appwrite-ios`, `appwrite-macos`, `appwrite-windows`, `appwrite-linux` and identifier is the host name is case of web apps and the package name in case of ios, android and other platforms.
146
-
-[ ] All Global headers available in spec
145
+
-[ ] Add 'origin' header with the following syntax `<scheme>://<identifier>` where scheme is one of `http`, `https`, `appwrite-android`, `appwrite-ios`, `appwrite-macos`, `appwrite-windows`, `appwrite-linux`. The identifier is host name for web apps and package name for iOS, Android and other platforms.
@@ -169,7 +169,7 @@ The following checklist aims to balance consistency among languages, and follow
169
169
170
170
## Tests
171
171
172
-
Testing a single project that runs in multiple languages can be very hard. Managing dependencies with multiple package managers of different ecosystems can take the SDK Generator complexity to extreme levels.
172
+
Testing a single project that runs in multiple languages can be difficult. Managing dependencies with multiple package managers of different ecosystems can take the SDK Generator complexity to extreme levels.
173
173
174
174
To avoid that complexity, we have created a cross-platform mechanism that leverages Docker and a vanilla language file with no dependencies attached.
175
175
@@ -183,14 +183,14 @@ To get started, create a language file in this ___location:
183
183
184
184
In your new language file, init your SDK from a relative path which will be generated here: `./tests/sdks/` from this spec file: `./tests/resources/spec.json`.
185
185
186
-
After you finish initializing, make a series of HTTP calls using your new generated SDKs method just like in one of these examples:
186
+
After you finish initializing, make a series of HTTP calls using your newly generated SDKs method just like in one of these examples:
187
187
188
188
1. tests/languages/php/test.php
189
189
2. tests/languages/node/test.js
190
190
191
191
> Note: In your test files, make sure that you begin the test with the following string "\nTest Started\n". We use this string to filter output from the build tool you're using.
192
192
193
-
Once done, create a new test file `tests/[Language]Test.php` and update as the following.
193
+
Once you're done, create a new test file `tests/[Language]Test.php` and update as the following.
194
194
195
195
```php
196
196
<?php
@@ -206,7 +206,7 @@ class [Language]Test extends Base
206
206
];
207
207
protected array $envs = [
208
208
// docker commands that can execute test file to the sdk test. Make sure to add
209
-
// one command for each lanuage version you wish to support
209
+
// one command for each language version you wish to support
210
210
];
211
211
212
212
// list of expected outputs from test based on features supported
@@ -248,39 +248,39 @@ class DartTest extends Base
248
248
}
249
249
```
250
250
251
-
Also in `.travis.yml` add new env `SDK=[Language]` so that travis will run test for this language as well.
251
+
Also in `.travis.yml` add new env `SDK=[Language]` so that travis will run a test for this language as well.
252
252
253
-
Finally, you can run tests using
253
+
Finally, you can run tests using:
254
254
```sh
255
255
docker run --rm -v $(pwd):$(pwd):rw -w $(pwd) -v /var/run/docker.sock:/var/run/docker.sock php:7.4-cli-alpine sh -c "apk add docker-cli && vendor/bin/phpunit"
256
256
```
257
257
258
258
## SDK Generator Interface
259
259
260
-
***spec** -- This object is derived from the appwrite swagger spec
260
+
***spec** -- This object is derived from the Appwrite swagger spec
261
261
***title** -> The title of the SDK you are generating (normally used as package name.)
***warning** -> Used for warnings usually communicated within the Readme.md
331
-
***gettingStarted** -> Raw Markdown for Getting Started
332
-
***readme** -> Stores the raw markdown used to generate the readme.md file. [here](https://github.com/appwrite/sdk-for-flutter/blob/master/README.md)
333
-
***changelog** -> Stores the raw markdown used to generate the changelog.md file. [here](https://github.com/appwrite/sdk-for-flutter/blob/master/CHANGELOG.md)
330
+
***warning** -> Used for warnings usually communicated within the `README.md`
331
+
***gettingStarted** -> Raw markdown for getting started
332
+
***readme** -> Stores the raw markdown used to generate the `README.md` file. [here](https://github.com/appwrite/sdk-for-flutter/blob/master/README.md)
333
+
***changelog** -> Stores the raw markdown used to generate the `changelog.md` file. [here](https://github.com/appwrite/sdk-for-flutter/blob/master/CHANGELOG.md)
334
334
***examples** -> Stores the raw markdown used to generate examples for your SDK. An example can be found [here](https://github.com/appwrite/sdk-for-flutter/tree/master/example)
Copy file name to clipboardExpand all lines: README.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,11 +8,11 @@
8
8
9
9
**WORK IN PROGRESS - NOT READY FOR GENERAL USAGE**
10
10
11
-
[Appwrite](https://appwrite.io) SDK generator is a PHP library for autogenerating SDK libraries for multiple languages and platforms.
11
+
[Appwrite](https://appwrite.io) SDK generator is a PHP library for auto-generating SDK libraries for multiple languages and platforms.
12
12
13
13
The SDK Generator uses predefined language settings as [Twig templates](https://twig.symfony.com/) to generate codebases based on different API specs.
14
14
15
-
Currently, the only spec supported is Swagger 2.0, but we intend to add support for more specifications in the near future. This generator is still lacking support for any definition/models specs.
15
+
Currently, the only spec supported is Swagger 2.0, but we intend to add support for more specifications in the near future. This generator is still lacking support for any definition/model specs.
All code contributions - including those of people having commit access - must go through a pull request and approved by a core developer before being merged. This is to ensure proper review of all the code.
137
+
All code contributions, including those by people with commit access, must go through a pull request and be approved by a core developer before being merged. This is to ensure proper review of all the code.
138
138
139
139
We truly ❤️ pull requests! If you wish to help, you can learn more about how you can contribute to this project in the [contribution guide](CONTRIBUTING.md).
0 commit comments