HTML Quis delectus ut vel error. Voluptatem fugiat nulla magni voluptatem. Aut eaque error autem. Animi aut ullam eveniet accusamus.Consequatur consequuntur dolore maxime consectetur nesciunt earum ullam. Hic ab tempore voluptatem iusto non qui consequatur. Est ullam pariatur qui dicta.
' +Random value example: 'HTML Veniam voluptatem perferendis magnam sit beatae voluptate. Veniam reprehenderit reiciendis fuga consequatur. Tempore et eos ad. Vero expedita sint et error harum.Eveniet vel itaque dolorem quod officia rerum debitis. Nesciunt velit ipsum fugiat. Sint nesciunt perspiciatis accusamus quos. Esse repudiandae temporibus reiciendis autem repellat.
' -SQL datatype: TEXT -Laravel SQL datatype: text('name') ## integer Datatype for integers, between -2147483648 and 2147483647. -Random value example: 545132295 +Random value example: 1698474726 -SQL datatype: INT -Laravel SQL datatype: integer("name") ## ip -Strings in UTF-8 and sanitized, up to 256 characters (which might be more than its bytes). +Strings in UTF-8 and sanitized, up to 39 characters (which might be more than its bytes). -Random value example: '133.232.127.115' +Random value example: 'a8d:c06e:bc52:f9cf:33b7:8686:3ce3:66a0' -SQL datatype: VARCHAR(39) -Laravel SQL datatype: ipAdddress('name') ## ipv4 Datatype for IPs in IPV4 format -Random value example: '148.121.67.59' +Random value example: '147.131.228.120' -SQL datatype: VARCHAR(256) -Laravel SQL datatype: string('name', 256) ## ipv6 Datatype for IPs in IPV6 format -Random value example: 'aff9:78c9:911f:dd78:c486:7388:b351:d31a' +Random value example: '23b6:5392:2cec:2fb4:5be3:e568:dc32:a95' -SQL datatype: VARCHAR(256) -Laravel SQL datatype: string('name', 256) ## json Valid JSON data -Random value example: '{"version":-1645684042,"data":{"string":"RHGJ2Ty","float":0.982}}' +Random value example: '{"version":-1026945324,"data":{"string":"RQ9Zci9lpNbxpGAHLh8Qnvvzzccej8","float":0.966}}' -SQL datatype: TEXT -Laravel SQL datatype: text('name') ## language -Languages. Names are in the actual language. Codes follow ISO 639-1 codes. +Languages. Names are in the actual language. This follows wikipedia, prefer 'languageiso2' for an ISO standard. + +Random value example: 'ht' + + + +## languageiso2 + +Languages represented by ISO630-1 2-letter codes. + +Random value example: 'lg' + + + +## name + +Just a plain string, but that expects a name. Generates good random names. -Random value example: 'et' +Random value example: 'Prof. Conrad Ankunding' -SQL datatype: VARCHAR(10) -Laravel SQL datatype: string(name, 10) ## phone A phone number in E164 format -Random value example: '+5412038893160' +Random value example: '+15409215003' -SQL datatype: VARCHAR(256) -Laravel SQL datatype: string('name', 256) ## string Strings in UTF-8 and sanitized, up to 256 characters (which might be more than its bytes). -Random value example: 'RhHe6zghDQGx' +Random value example: 'R1Aa6' -SQL datatype: VARCHAR(256) -Laravel SQL datatype: string('name', 256) ## text -Strings in UTF-8 and sanitized, up to 1024000 characters (which might be more than its bytes). +Long text in UTF-8 and sanitized, up to 1024000 characters (which might be more than its bytes). -Random value example: 'Est perferendis tempora accusamus voluptatem earum asperiores. Deserunt sed enim consequuntur ducimus culpa. Deserunt eos asperiores harum culpa.' +Random value example: 'Id dolorem assumenda voluptatem est tenetur ab. Animi enim aut ullam possimus tempora aut. Aperiam nemo reiciendis quis eos. Cum minima voluptas perferendis voluptates.' -SQL datatype: TEXT -Laravel SQL datatype: text('name') ## time Time (HH:MM:SS). -Random value example: '15:16:56' +Random value example: '17:42:29' -SQL datatype: TIME -Laravel SQL datatype: time('name', 0) ## timestamp Timestamps. Just like datetime, but might be a different type in your database. -Random value example: '2011-07-19T14:01:40-0300' +Random value example: '2014-10-13T02:22:07-0300' -SQL datatype: TIMESTAMP -Laravel SQL datatype: timestamp('name') ## timezone Timezones. Follows PHP timezone_identifiers_list(). -Random value example: 'Africa/Windhoek' +Random value example: 'Europe/Istanbul' -SQL datatype: VARCHAR(50) -Laravel SQL datatype: string(name, 50) ## uinteger Datatype for unsigned integers, between 0 and 4294967296. -Random value example: 767598853 +Random value example: 1899136886 -SQL datatype: INT UNSIGNED -Laravel SQL datatype: integer("name")->unsigned() ## url Datatype for URLs -Random value example: 'http://www.vandervort.com/sit-ea-excepturi-similique-sit-sequi.html' +Random value example: 'http://mcdermott.org/sunt-magnam-repellendus-ipsum-voluptatem' -SQL datatype: VARCHAR(256) -Laravel SQL datatype: string('name', 256) ## usmall Datatype for unsigned small integers, between 0 and 65536. -Random value example: 53473 +Random value example: 35275 -SQL datatype: SMALLINT UNSIGNED -Laravel SQL datatype: smallInteger("name")->unsigned() ## uuid Datatype for uuid values. -Random value example: '40930740-56d7-4981-8bda-e0a9ba2f044c' +Random value example: '1e543e7e-d2a6-4d42-bce8-1b5b378e62dc' -SQL datatype: CHAR(16) -Laravel SQL datatype: uuid('name') ## year Valid years. May create a special field in the database. -Random value example: 935433446 +Random value example: 2005 -SQL datatype: INT -Laravel SQL datatype: year('name') diff --git a/docs/api-directives.md b/docs/api-directives.md new file mode 100644 index 0000000..56c95e4 --- /dev/null +++ b/docs/api-directives.md @@ -0,0 +1,334 @@ +--- +nav_order: 12 +--- + +# Directive reference + +Directives supported by Modelarium. + +## @casts + +```graphql +""" +Casts type +""" +directive @casts( + """ + The value + """ + type: String! +) on FIELD_DEFINITION +``` + +## @eagerLoad + +```graphql +""" +Eager load relationships using Laravel Model::$with(); +""" +directive @eagerLoad ( + """ + If present, use this name as the with($name) parameter. Otherwise try to guess from field. + """ + name: String + + """ + If present, append these values to the with($name) model class. + """ + tables: [String!] +) on FIELD_DEFINITION | OBJECT +``` + +## @frontendSkip + +```graphql +""" +Do not generate frontend for this type +""" +directive @frontendSkip on OBJECT +``` + +## @hidden + +```graphql +""" +Make this field hidden. It will not show up on introspection or queries. +""" +directive @hidden on FIELD_DEFINITION +``` + +## @migrationAlterTable + +```graphql +""" +Alters a table on migration after it was created. +""" +directive @migrationAlterTable( + """ + The commands to run, which will be prepended with 'ALTER TABLE tablename" + """ + values: [String!]! +) on OBJECT +``` + +## @migrationDefaultValue + +```graphql +""" +Default value for database column +""" +directive @migrationDefaultValue( + """ + The value + """ + value: String! +) on FIELD_DEFINITION +``` + +## @migrationForeign + +```graphql +""" +Foreign keys +""" +directive @migrationForeign( + """ + What field it references + """ + references: String + + """ + What table it references + """ + on: String + + """ + What to do onDelete + """ + onDelete: String + + """ + What to do on Update + """ + onUpdate: String +) on FIELD_DEFINITION +``` + +## @migrationFulltextIndex + +```graphql +""" +Add a full text index to table +""" +directive @migrationFulltextIndex( + """ + The fields to index. Must be an array even if it is just one field. + """ + fields: [String!]! +) on OBJECT +``` + +## @migrationIndex + +```graphql +""" +Generates a composed index on the database for a type +""" +directive @migrationIndex( + """ + The list of fields to compose in the index + """ + fields: [String!]! +) on OBJECT +``` + +## @migrationRememberToken + +```graphql +""" +Specifies that remember me tokens should be created on DB. +""" +directive @migrationRememberToken on OBJECT +``` + +## @migrationSkip + +```graphql +""" +Do not add this field to the migration +""" +directive @migrationSkip on FIELD_DEFINITION +``` + +## @migrationSoftDeletes + +```graphql +""" +Specifies a soft delete mode for this type +""" +directive @migrationSoftDeletes on OBJECT +``` + +## @migrationSpatialIndex + +```graphql +""" +Generates a migrationSpatialIndex +""" +directive @migrationSpatialIndex( + """ + The field for the index + """ + field: String! +) on OBJECT +``` + +## @migrationTimestamps + +```graphql +""" +Generates a timestamps columns for a type +""" +directive @migrationTimestamps on OBJECT +``` + +## @migrationUniqueIndex + +```graphql +""" +Generates a unique index on the database for that field +""" +directive @migrationUniqueIndex ( + """ + The list of fields to compose in the index + """ + fields: [String!] +) on FIELD_DEFINITION | OBJECT +``` + +## @modelAccessor + +```graphql +""" +Creates an accessor method in the class. +""" +directive @modelAccessor on FIELD_DEFINITION +``` + +## @modelExtends + +```graphql +""" +Base class to extend on model. +""" +directive @modelExtends( + """ + The base class name with namespace + """ + class: String! +) on OBJECT +``` + +## @modelFillable + +```graphql +""" +Field is added to Model::$fillable +""" +directive @modelFillable on FIELD_DEFINITION +``` + +## @modelHidden + +```graphql +""" +Field is added to Model::hidden +""" +directive @modelHidden on FIELD_DEFINITION +``` + +## @modelMustVerifyEmail + +```graphql +""" +Use a MustVerifyEmail trait on a model +""" +directive @modelMustVerifyEmail on OBJECT +``` + +## @modelNotifiable + +```graphql +""" +Use a Notifiable trait on a model +""" +directive @modelNotifiable on OBJECT +``` + +## @modelSkip + +```graphql +""" +Do not generate model (and seeder/factory/etc) for this type +""" +directive @modelSkip on OBJECT +``` + +## @morphedByMany + +```graphql +""" +Handles the target of morphMany +""" +directive @morphedByMany on FIELD_DEFINITION +``` + +## @renderable + +```graphql +""" +Generate renderable +""" +directive @renderable ( + """Label for this field""" + label: String + + """Comment for this field""" + comment: String + + """Should this field be used in show pages?""" + show: Boolean + + """Is this field the title field for this object?""" + title: Boolean + + """Should this field be used in the form? Default is true""" + form: Boolean + + """Should this field be used in card components?""" + card: Boolean + + """Should this field be used in table components?""" + table: Boolean + + """Field size in render""" + size: String + + # move to schemaRenderable() + itemtype: String + + # move to typeRenderable() + routeBase: String + keyAttribute: String + name: String +) on FIELD_DEFINITION | OBJECT +``` + +## @typeSkip + +```graphql +""" +Do not process this type in Modelarium. Will not create models, migrations, etc +""" +directive @typeSkip on OBJECT | ENUM +``` diff --git a/docs/laraveltutorial.md b/docs/laraveltutorial.md index 1f3c0ac..9bee481 100644 --- a/docs/laraveltutorial.md +++ b/docs/laraveltutorial.md @@ -329,6 +329,8 @@ npm run watch ## Authentication +There's nothing specific to Modelarium about authentication, and all the usual methods of authenticating will work. But this is a tutorial, so let's show how to add authentication to our app. + By default Modelarium creates models in `app/Models` instead of `app`. For this to work with authentication you should change this in `config/auth.php`. You can also pass `--modelDir=app` if you prefer Laravel's default behavior. ```php diff --git a/docs/philosophy.md b/docs/philosophy.md index 03e44ed..1adc0dd 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -6,6 +6,8 @@ nav_order: 2 The idea behind Modelarium is to avoid tedious coding and increase safety. +## Why web programming became tedious and error prone + Imagine you are changing a model and adding a single new field. The usual way to do it in Laravel is more or less this: 1. Add a migration. @@ -26,6 +28,25 @@ Imagine you are changing a model and adding a single new field. The usual way to This is a lot of work, very prone to typos, bugs, or forgetting something. Most of it is easy to automatize. That's why Modelarium was created. +## What Modelarium does to solve it + +Modelarium generates scaffolding for your project based on a GraphQL description of your API. It can create the entire backend and frontend files, leaving only the logic and design for you. + +- **generates backend scaffolding for you**: model, database migration, seed, factory, events, policies. Everything from your graphql descriptions. No more tedious creation of files and repeated code. +- **datatypes**: your data is more than strings. You have models for your structures, so have datatypes for your fields. Create the correct database fields without thinking about it. Uses [Formularium for datatypes](https://corollarium.github.io/Formularium/). +- **validation**: transparent data validation made automatically based on your datatypes. Your data is always safely validated. +- **no performance penalty**: other than data validation all data is generate at development time. It's just automatic scaffolding, everything is just as fast as before. +- **no new standards**: code is generated following existing standards for existing tools. Generate code and use it freely. Nothing is tied down. +- **frontend generation**: get HTML forms, cards, lists and views generated for you automatically with your favorite CSS framework: Bootstrap, Bulma, Materialize, Buefy with simple declarations and a standard description. You can tweak details afterwards -- it's just code. +- **reactive frameworks**: Get Vue and React components like cards, forms, lists and tables, ready to use with their Graphql calls. +- **integration with Laravel and Lighthouse**. Get GraphQL endpoints automatically. + +What it doesn't do: + +- magic. you still have to write your code logic to process requests in the backend, like in mutations or special conditions in your models. You also get only a basic design, so pretty CSS is up to you. +- REST endpoints generation. At this point only GraphQL is supported through Laravel and Lighthouse. REST endpoints might come later. +- other backend frameworks. Currently only Laravel is supported. + ## Why data types? Even in strongly typed languages we often use just the base types, such as float or string, for different things. For example, we use a string for an email field, or a float for a velocity field. This is not rare [and a space probe was once lost due to different units used in computation](https://www.nasa.gov/centers/ames/research/exploringtheuniverse/exploringtheuniverse-computercheck.html). diff --git a/util/MakeAPIDoc.php b/util/MakeAPIDoc.php index 6a45ab6..cb41bf5 100644 --- a/util/MakeAPIDoc.php +++ b/util/MakeAPIDoc.php @@ -30,9 +30,9 @@ function (\ReflectionClass $reflection): array { nav_order: 12 --- -# Datatypes +# Datatype reference -List of validators and its parameters generated automatically. +List of datatypes and its parameters generated automatically. ' . join("\n", $markdown);