Commit history cleanup

.github/workflows/dependency-review.yml

@@ -0,0 +1,39 @@
+# Dependency Review Action
+#
+# This Action will scan dependency manifest files that change as part of a Pull Request,
+# surfacing known-vulnerable versions of the packages declared or updated in the PR.
+# Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable
+# packages will be blocked from merging.
+#
+# Source repository: https://github.com/actions/dependency-review-action
+# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
+name: 'Dependency review'
+on:
+  schedule:
+    - cron: '45 3 */3 * *'
+  workflow_dispatch:
+# If using a dependency submission action in this workflow this permission will need to be set to:
+#
+# permissions:
+#   contents: write
+#
+# https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api
+permissions:
+  contents: read
+  # Write permissions for pull-requests are required for using the `comment-summary-in-pr` option, comment out if you aren't using this option
+  pull-requests: write
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout repository'
+        uses: actions/checkout@v4
+      - name: 'Dependency Review'
+        uses: actions/dependency-review-action@v4
+        # Commonly enabled options, see https://github.com/actions/dependency-review-action#configuration-options for all available options.
+        with:
+          comment-summary-in-pr: always
+        #   fail-on-severity: moderate
+        #   deny-licenses: GPL-1.0-or-later, LGPL-2.0-or-later
+        #   retry-on-snapshot-warnings: true

.github/workflows/php.yml

@@ -0,0 +1,26 @@
+name: PHP Composer
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate
+
+    - name: Install dependencies
+      run: composer install --prefer-dist --no-progress --no-suggest
+
+    - name: Run Tests
+      run: composer run-script tests
+
+    # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
+    # Docs: https://getcomposer.org/doc/articles/scripts.md
+
+    # - name: Run test suite
+    #   run: composer run-script test

.gitignore

@@ -0,0 +1,7 @@
+\.idea/
+vendor/
+docs/
+\.buildpath
+\.project
+\.settings/
+*.cache

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+	"recommendations": [
+		"bmewburn.vscode-intelephense-client"
+	]
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "intelephense.format.braces": "k&r"
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Daniel Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,112 @@
+# CCidadao
+
+CCidadao is a PHP Class used to validate and generate Citizen Card numbers.
+
+## How to use
+
+### Instalation
+
+CCidadao is available on [Packagist](https://packagist.org/)! You can install it via [Composer](https://getcomposer.org/), by typing:
+
+`$ composer require Dannyps/CCidadao`
+
+The class will be auto-loaded by composer. Thus, in order to use it, you need only `require 'vendor/autoload.php';` in your PHP script.
+
+### Softening the curve
+
+Portuguese Citizen Cards are a complicated subject.
+They have two check digits, and a weird version control system.
+Internal variables contain the following fields:
+
+In the example number:
+
+```
+12345678 9 ZZ 0
+┃        ┃ ┃  ┃
+┃        ┃ ┃  ┗━━━> Versioned check digit ----> $vcd
+┃        ┃ ┗━━━━━━> Version chars ------------> $vcc
+┃        ┗━━━━━━━━> Constant check digit -----> $ccd
+┗━━━━━━━━━━━━━━━━━> the number itself --------> $num
+```
+ * The version chars represent the version of the document in the following manner:
+- ZZ => v1
+- ZY => v2
+- ZX => v3
+- ...
+- ZA => v26
+- YZ => v27
+- etc...
+Both `$ccd` and `$vcd` can be determined, provided the `$num` and `$ver/$vcc` are available, respectively.
+
+Moreover, the `$ccd` depends solely on the `$num`, whereas the `$vcd` depends on the `$num` and on the `$vcc`.
+
+### Code Examples
+
+Test code is a good place to start. However, code examples are displayed below for your convenience.
+
+#### Generating an array of _valid_ CC numbers.
+_Note: The fact these numbers are valid does not mean they are being used by anyone._
+
+```php
+<?php
+require 'vendor/autoload.php';
+use Dannyps\CCidadao\CCidadao;
+
+$ver = [
+    'min' => 1,
+    'max' => 2,
+];
+
+$beg = 15000000;
+$end = 15000100;
+
+$arr = [];
+
+for ($i = $beg; $i < $end; $i++) {
+    for ($j = $ver['min']; $j <= $ver['max']; $j++) {
+        array_push($arr, (new CCidadao($i . "_", $j))->__toString());
+    }
+}
+
+// $arr now contains versions 1 and 2 of all CCs from 15000000 to 15000100. These are valid values.
+```
+#### Getting the next version of a CC number
+
+As time goes by, people get new Citizen Cards. However, their numbers are already predestined. Because of the algorithm used, it is possible to foresee all possible numbers. Moreover, we know these numbers are sequential.
+
+```php
+<?php
+require 'vendor/autoload.php';
+use Dannyps\CCidadao\CCidadao;
+
+$cc = new CCidadao("15632563ZZ7");
+$cc->next(); // advance current cc
+echo ($cc);
+
+// -- another method --
+
+echo new CCidadao("15632563", 2);
+```
+
+#### Validating a CC number
+
+```php
+<?php
+require 'vendor/autoload.php';
+use Dannyps\CCidadao\CCidadao;
+
+try {
+    new CCidadao("15632563ZZ7");
+} catch(Exception $e){
+    // invalid
+}
+```
+
+## Motivation
+There was an interest in being able to quickly generate valid CC numbers for pentesting reasons. Thus, CCidadao was born. Its applications, however, are more abrangent than that.
+
+## Contributing
+You are welcome to contribute to the code, as well as to the documentation. You should do so by means of a Pull Request. You may use xDebug to profile the execution and find the less effecient methods.
+
+## How does it work?
+The algorithms to determine both control digits are available online, in some blogs and similar pages. Testing of this class began with real CC numbers, as this was the only way to make sure the code was developed according to reality.

composer.json

@@ -0,0 +1,26 @@
+{
+	"name" : "dannyps/ccidadao",
+	"description" : "A class for generating and validating Portuguese Citizen Card (CC aka Cartão de Cidadão) Numbers.",
+	"require" : {
+		"php" : ">=7.0.0 || >=8.0.0"
+	},
+	"license" : "MIT",
+	"require-dev" : {
+		"phpunit/phpunit" : ">=9"
+	},
+	"authors" : [{
+			"name" : "Daniel Silva",
+			"email" : "mail@dannyps.net",
+			"homepage" : "https://dannyps.net",
+			"role" : "Author"
+		}
+	],
+	"autoload" : {
+		"classmap" : [
+			"src/"
+		]
+	},
+	"scripts": {
+		"tests": "vendor/bin/phpunit tests/*"
+	}
+}