# SimpleSAMLphp developer information [TOC] This document is intended to provide an overview of the code for developers. It should be readable to new developers and developers who contribute as time allows and may have forgotten some details over time. ## Overview This is a living document and various sections and additions are being made as my knowledge of the SSP code and environment expands. Hopefully this can help others find their way around the code a bit quicker. The `master` branch is where active development of the next release is taking place. If you would like to contribute an update to and existing release please checkout the branch for that release, for example to make a contribution to the v2.1.1 release you would checkout the [simplesamlphp-2.1 branch](https://github.com/simplesamlphp/simplesamlphp/tree/simplesamlphp-2.1). ## Libraries that SimpleSAMLphp uses and planned changes Many dependencies are listed in the require clause of the composer.json such as Symfony, Twig, and simplesamlphp/saml2. As at early 2024 there is a plan to move from using robrichards/xmlseclibs to using the newly written [xml-security library](https://github.com/simplesamlphp/xml-security). The integration of xml-security started in the v5 of the saml2 library. The saml2 library is already a dependency of SimpleSAMLphp and is brought in with composer as a [dependency here.](https://github.com/simplesamlphp/simplesamlphp/blob/15019f97eb1b4041859582b8b6f39fe432b603af/composer.json#L66C21-L66C29). ## Build process There are two main release targets for each release: slim and full. This is done by the [build-release.yml](https://github.com/simplesamlphp/simplesamlphp/blob/master/.github/workflows/build-release.yml) script. The full version also contains some [simplesamlphp modules](https://github.com/simplesamlphp/simplesamlphp/blob/master/.github/build/full.json). The build will also include some files in the vendor directory in the full build that are not in the slim build. If the SimpleSAMLphp code relies on other repositories on the [simplesamlphp](https://github.com/simplesamlphp) site then they are brought in using composer as shown for example for the [saml2 library](https://github.com/simplesamlphp/simplesamlphp/blob/435ce92874a789101495504cd6c4da600fb01334/composer.json#L73). ## Code checks The github actions perform some linting and checks on the php code. The linting is done with super-linter and the php checks with phpcs. You can run the phpcs checks locally by executing `phpcs` in the root of the git repository. If you would like your simpler issues to be solved for you execute `phpcbf` which will update the code to remedy as many issues as it can. ## CSS and common asset setup The common assets such as CSS in SimpleSAMLphp, for example, that stored in public/assets/base/css/stylesheet.css comes from the [simplesamlphp-assets-base](https://github.com/simplesamlphp/simplesamlphp-assets-base) package. The dependencies are updated using github actions in simplesamlphp-assets-base. Select a recent branch such as release-2.2 and dig into the .github directory for details. ## Following a simple login The `SimpleSAML\Auth\Simple` class takes the authentication_source name and can be used to find a login URL with `getLoginURL()`. The getLoginURL method takes the return URL as it's only parameter. The URL returned from `getLoginURL()` will be a request to module.php and include the return URL information. The module.php code `Module::process`. The `process` method uses Symfony to dispatch the request. This may result in a call to modules/core/src/Controller/Login.php in `Login::loginuserpass()`. The code flows through `handleLogin()` which may call `UserPassBase::handleLogin(authstateid, username, password)`. The `handleLogin` method looks up the `$as = Auth\Source` and passes the login credentials to the `$as->login( username, password )` method. For an SQL based login this would be in modules/sqlauth/src/Auth/Source/SQL.php and the `SQL::login` method. This `login` method either returns the user attributes on success or throws an exception on login failure. ## Documentation The core of the simplesamlphp.org website is taken from [simplesamlphp.github.io](https://github.com/simplesamlphp/simplesamlphp.github.io). The [docs subdirectory](https://simplesamlphp.org/docs/) is built from the [docs subdirectory](https://github.com/simplesamlphp/simplesamlphp/tree/master/docs) of the main repository on github. ### Documentation updates There are two main repositories for documentation. The website itself comes from one place and everything that is under the "Documentation" menu uses another process . The website lives in That only has a "release" branch to commit to, which is the website as it is shown. There you'd commit to change the pages on the website, e.g. to the page /contrib/ The "docs" repo (as described in the readme of the repo) only contains the scripts that generate the docs website. In order to improve the content of the documentation themselves, you commit using the same branches used for code contributions at . You can address documentation updates to master . Though it makes sense to backport them to supported releases, so each version under will show the change. In other words, if a documentation change relates to 2.1.3 you might like to make the pull request against the simplesamlphp-2.1 branch and leave it to the team to also apply it to master and other branches in the same way that code updates work. Some docs offered under the `docs` directory on the web site come from modules. For example the [saml module](https://simplesamlphp.org/docs/2.3/saml/sp.html) file comes from the file `./modules/saml/docs/sp.md` in the git repository. ### Documentation linting The CI system has some linting for markdown files in place. This uses `github-action-markdown-cli` to perform the work which itself uses `markdownlint-cli`. You can install the latter with npm install and then setup the rc file from github-action-markdown-cli from to run the linter locally. For example, with the markdownlintrc from above in a local file you could use the following if you have not globally installed markdownlint. The `--fix` option will have markdownlint fix simpler issues for you so you can concentrate on the document and not the fine details of the syntax formatting. ```bash npm install markdownlint-cli cd ./node_modules/.bin # copy the markdown lint file to markdownlintrc ./markdownlint -c markdownlintrc /tmp/simplesamlphp-developer-information.md ./markdownlint -c markdownlintrc --fix /tmp/simplesamlphp-developer-information.md ``` You will probably want to make a script or alias to the above command and apply it before pushing documentation changes to github. ## Making a release The release process is documented on the wiki . ## Dependbot The dependbot runs on the master branch and creates pull requests with recommended updates. The release branches are updated automatically as part of the release process.