Skip to content

Commit

Permalink
docs: finalize how it works docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@dshafik
dshafik committed May 7, 2024
1 parent 6f17f02 commit 02fb1b3
Show file tree
Hide file tree
Showing 2 changed files with 120 additions and 15 deletions.
10 changes: 8 additions & 2 deletions docs/.vitepress/theme/custom.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,21 @@ code {
}

.mermaid-decision > polygon {
fill: var(--vp-custom-block-caution-bg) !important;
stroke: var(--vp-custom-block-caution-text) !important;
fill: var(--vp-c-yellow-soft) !important;
stroke: var(--vp-c-yellow-1) !important;
}

.mermaid-conditional > rect {
fill: var(--vp-c-purple-soft) !important;
stroke: var(--vp-c-purple-1) !important;
}

.mermaid-error > rect {
fill: var(--vp-c-danger-soft) !important;
stroke: var(--vp-c-danger-1) !important;

}

.mermaid-end > rect {
fill: var(--vp-c-success-soft) !important;
stroke: var(--vp-c-success-1) !important;
Expand Down
125 changes: 112 additions & 13 deletions docs/how-bag-works.md
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,36 @@
# How Bag Works

Bag works by utilizing a pipelines to process the input and output data. There is an `InputPipeline` and an `OutputPipeline`.
Bag works by utilizing a pipelines to process the input and output data.

There are four pipelines:

- `InputPipeline` for handling input and constructing the Bag object
- `ValidationPipeline` for validating without constructing the Bag object
- `OutputPipeline` for handling output
- `OutputCollectionPipeline` for handling collection output

Each pipeline is detailed below.

> [!TIP]
> Each stage in the diagrams below is linked to the relevant source code for that stage.
## The Input Pipeline

The `InputPipeline` is responsible for processing the input data so that the `Bag` object can be created. The pipeline
The [`InputPipeline`](https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/InputPipeline.php) is responsible for processing the input data so that the `Bag` object can be created. The pipeline
consists of the following steps:

```mermaid
graph TD;
start("Bag::from($data)")
--> transform(Transform Input)
--> process(Process Parameters)
--> map(Create Name Map)
--> variadic(Is Variadic?)
--> mapInput(Map Input)
--> fill(Fill Laravel Request Params)
-- Finalized Input Values --> missing{Missing Parameters?}
missing -- Yes --> errorMissingProperties(MissingPropertiesException)
missing -- No --> extra{Extra Parameters?}
extra -- Yes --> errorExtraProperties(ExtraPropertiesException)
extra -- No --> validate(Validate)
-- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
missingError -- Yes --> errorMissingParameters(MissingPropertiesException)
missingError -- No --> extra(Extra Parameters) --> extraError{Error?}
extraError -- Yes --> errorExtraParameters(ExtraPropertiesException)
extraError -- No --> validate(Validate)
--> valid{Valid?}
valid -- No --> errorValidation(ValidationException)
valid -- Yes --> cast(Cast Input)
Expand All @@ -32,10 +42,21 @@ initialized -- Yes
--> bag(Bag Value Returned)
class start mermaid-start
class missing,extra,valid,initialized mermaid-decision
class missingError,extraError,valid,initialized mermaid-decision
class bag mermaid-end
class errorMissingParameters,errorExtraParameters,errorValidation,errorInitialization mermaid-error
click transform "https://dshafik.github.io/bag"
click start "https://github.com/dshafik/bag/blob/main/src/Bag/Bag.php" _blank
click transform "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Transform.php" _blank
click process "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ProcessParameters.php" _blank
click variadic "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/IsVariadic.php" _blank
click mapInput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MapInput.php" _blank
click missing "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MissingParameters.php" _blank
click extra "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ExtraParameters.php" _blank
click validate "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Validate.php" _blank
click cast "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/CastInputValues.php" _blank
click construct "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/FillBag.php" _blank
click computed "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ComputedValues.php" _blank
```

## The Output Pipeline
Expand All @@ -46,7 +67,9 @@ The `OutputPipeline` is responsible transforming the Bag data to the desired out
graph TD;
toArray("Bag->toArray()") --> processParameters
toJson("Bag->toJson()") --> processParameters
jsonEncode("json_encode($bag)") --> processParameters
get("Bag->get()") --> processParameters
unwrapped("Bag->unwrapped()") --> processParameters
processParameters(Process Parameters)
--> processProperties(Process Properties)
--> getValues(Get Values)
Expand All @@ -57,10 +80,86 @@ processParameters(Process Parameters)
--> wrap(Wrap Output*)
--> output(array or JSON string)
class toArray,toJson,get mermaid-start
class toArray,toJson,jsonEncode,get,unwrapped mermaid-start
class output mermaid-end
class hide,hideJson,wrap mermaid-conditional
click toArray "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithArrayable.php" _blank
click toJson "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithJson.php" _blank
click get "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithOutput.php" _blank
click unwrapped "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithOutput.php" _blank
click processParameters "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ProcessParameters.php" _blank
click processProperties "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ProcessProperties.php" _blank
click getValues "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/GetValues.php" _blank
click hide "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/HideValues.php" _blank
click hideJson "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/HideJsonValues.php" _blank
click cast "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/CastOutputValues.php" _blank
click mapOutput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MapOutput.php" _blank
click wrap "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Wrap.php" _blank
```

> [!NOTE]
> \* These steps are only performed if the Bag is being converted to an array and/or JSON.
## The Validation Pipeline

The `ValidationPipeline` is responsible for validating the input data without constructing the Bag object. The pipeline consists of the following steps:

```mermaid
graph TD;
start("Bag::validate($data)")
--> transform(Transform Input)
--> process(Process Parameters)
--> variadic(Is Variadic?)
--> mapInput(Map Input)
-- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
missingError -- Yes --> errorMissingParameters(MissingPropertiesException)
missingError -- No --> extra(Extra Parameters) --> extraError{Error?}
extraError -- Yes --> errorExtraParameters(ExtraPropertiesException)
extraError -- No --> validate(Validate)
--> valid{Valid?}
valid -- No --> errorValidation(ValidationException)
valid -- Yes --> success(return true)
class start mermaid-start
class missingError,extraError,valid mermaid-decision
class success mermaid-end
class errorMissingParameters,errorExtraParameters,errorValidation mermaid-error
click start "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithValidation.php" _blank
click transform "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Transform.php" _blank
click process "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ProcessParameters.php" _blank
click variadic "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/IsVariadic.php" _blank
click mapInput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MapInput.php" _blank
click missing "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MissingParameters.php" _blank
click extra "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ExtraParameters.php" _blank
click validate "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Validate.php" _blank
```

## The Output Collection Pipeline

The `OutputCollectionPipeline` is responsible for transforming the Bag collection data to the desired output array or JSON. The pipeline consists of the following steps:

```mermaid
graph TD;
toArray("Collection->toArray()") --> wrap
toJson("Collection->toJson()") --> wrap
jsonEncode("json_encode($collection)") --> wrap
unwrapped("Collection->unwrapped()") --> wrap
wrap(Wrap Collection*)
--> output(array or JSON string)
class toArray,toJson,jsonEncode,unwrapped mermaid-start
class output mermaid-end
click toArray "https://github.com/dshafik/bag/blob/main/src/Bag/Collection.php" _blank
click toJson "https://github.com/dshafik/bag/blob/main/src/Bag/Collection.php" _blank
click jsonEncode "https://github.com/dshafik/bag/blob/main/src/Bag/Collection.php" _blank
click unwrapped "https://github.com/dshafik/bag/blob/main/src/Bag/Collection.php" _blank
click wrap "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/WrapCollection.php" _blank
```

> [!NOTE]
> \* These steps are only performed if the Bag is being converted to an array or JSON.
> \* This step is only performed if the Bag is being converted to an array and/or JSON.

0 comments on commit 02fb1b3

Please sign in to comment.