|
1 | | -GEWIS Website |
2 | | -============= |
| 1 | +<div align="center"> |
| 2 | + <h1>GEWISWEB - The GEWIS Website</h1> |
3 | 3 |
|
4 | | -Website for Study association GEWIS. All information regarding the development can be found in the [wiki](https://github.com/GEWIS/gewisweb/wiki). |
| 4 | +<!-- Shield group --> |
| 5 | +[](https://github.com/GEWIS/gewisweb/releases) |
| 6 | +[](https://github.com/GEWIS/gewisweb/actions) |
| 7 | +[](https://gewis.nl/en/) |
| 8 | +[](https://github.com/GEWIS/gewisweb/issues) |
| 9 | +[](https://github.com/GEWIS/gewisweb/commits/main) |
| 10 | +[](./LICENSE.txt) |
| 11 | + |
| 12 | +<p>GEWISWEB is the <a href="https://gewis.nl" target="_blank">website</a> created by and for the members of GEWIS — <em>GEmeenschap van Wiskunde en Informatica Studenten</em>.</p> |
| 13 | +</div> |
| 14 | + |
| 15 | +## Features |
| 16 | +The GEWIS website provides its members and other visitors with lots of functionality: |
| 17 | + |
| 18 | +- **Activities**: |
| 19 | + - Create activities with a wide range of options for sign-up lists. |
| 20 | + - Enables members to sign up for various events and activities, enhancing engagement and participation. |
| 21 | + |
| 22 | +- **Companies**: |
| 23 | + - Allows companies that collaborate with GEWIS to publish job vacancies and opportunities. |
| 24 | + - Facilitates connections between students and potential employers, aiding in career development. |
| 25 | + |
| 26 | +- **Decisions**: |
| 27 | + - Provides a platform for members to view and interact with decisions and meetings. |
| 28 | + - Ensures transparency and member involvement in the decision-making process. |
| 29 | + |
| 30 | +- **Education**: |
| 31 | + - Offers an extensive archive of course documents, including exams and summaries. |
| 32 | + - Serves as a valuable resource for students looking to study or review past materials. |
| 33 | + |
| 34 | +- **Pages**: |
| 35 | + - Custom pages created by the board to provide dynamic content. |
| 36 | + - Allows for flexible and timely updates to information and announcements. |
| 37 | + |
| 38 | +- **Photos**: |
| 39 | + - Maintains a comprehensive photo archive of the numerous activities organised by GEWIS. |
| 40 | + - Helps preserve and share memories of events and gatherings with the community. |
| 41 | + |
| 42 | +And there is plenty more! GEWISWEB continuously evolves to meet the needs of the association's members, offering a broad array of tools and features to enrich their time at the university. |
| 43 | + |
| 44 | +## Getting Started |
| 45 | +GEWISWEB is built on PHP and the [Laminas MVC framework](https://getlaminas.org/). The Laminas MVC framework provides a solid foundation for building scalable and maintainable web applications. |
| 46 | + |
| 47 | +### Prerequisites |
| 48 | +We recommend developing natively on a Linux machine or through WSL2 on Windows (note: Arch-based distributions are **not** recommended) with the [PhpStorm](https://www.jetbrains.com/phpstorm/) IDE or another IDE with good IntelliSense support for PHP. |
| 49 | + |
| 50 | +You will need at least: |
| 51 | +- `docker` and `docker compose` (make sure that you have enabled [Buildkit](https://docs.docker.com/build/buildkit/#getting-started)) |
| 52 | +- `gettext` utilities |
| 53 | +- `git` |
| 54 | +- `make` |
| 55 | +- A `.po` file editor (e.g. POEdit) |
| 56 | + |
| 57 | +Some of the `make` commands run natively on your machine; as such, you may also need to install PHP itself (use the `ondrej/php` PPA for `apt` to get the latest version) and [`composer`](https://getcomposer.org/download/). |
| 58 | + |
| 59 | +### Installation |
| 60 | +To set up GEWISWEB locally, follow these steps: |
| 61 | + |
| 62 | +1. [Fork the repository](https://github.com/GEWIS/gewisweb/fork). |
| 63 | +2. Clone your fork (`git clone git@github.com:{username}/gewisweb.git`). |
| 64 | +3. Copy the `.env.dist` file to `.env` and alter the file to your needs. |
| 65 | +4. Run `make rundev` to build and serve the website (this may take 5-10 minutes). |
| 66 | +5. Run `make migrate` and `make seed` to get some test data. |
| 67 | +6. Go to `http://localhost/` in your browser and you are greeted with the GEWIS website. |
| 68 | +7. Log in with membership number `8000` and the password `gewiswebgewis`. |
| 69 | + |
| 70 | +### Contributing |
| 71 | +We welcome contributions from the community, especially GEWIS members! To contribute: |
| 72 | + |
| 73 | +1. Perform the steps from [Installation](#installation). |
| 74 | +2. Create your feature of bug fix branch (`git switch -c feature/my-amazing-feature`). |
| 75 | +3. Commit your changes (`git commit -m 'feat: added my amazing feature'`). |
| 76 | +4. Push to the branch (`git push origin feature/my-amazing-feature`). |
| 77 | +5. Open a pull request. |
| 78 | + |
| 79 | +More detailed information on GEWIS' contribution guidelines, including conventions on branch names and commit messages, can be found [here](https://github.com/GEWIS/.github/blob/main/CONTRIBUTING.md). |
| 80 | + |
| 81 | +### Project Structure |
| 82 | +A general overview of important folders required for the functioning of the website: |
| 83 | + |
| 84 | +```txt |
| 85 | +./ |
| 86 | +├── config # Global configuration files for the website. |
| 87 | +├── data # Persistent private data-related files, such as cryptographic keys and logs. |
| 88 | +├── docker # Docker-related files to construct the containers. |
| 89 | +├── module # Contains the modules that make up the website, each providing specific features. |
| 90 | +└── public # Publicly accessible files, including the entry point (index.php). |
| 91 | +``` |
| 92 | + |
| 93 | +We make use of the Model-View-Controller framework. Generally speaking, the model layer is responsible for the interaction with the database and data manipulation. Next, the view layer is responsible for rendering data into a web page. The controller is responsible for processing the request and interacts with the model and view layer to provide a response. |
| 94 | + |
| 95 | +To make development easier (and due to how the Laminas MVC framework works) we add some extra layers and arrive at a structure for each module that looks like this: |
| 96 | + |
| 97 | +```txt |
| 98 | +./ |
| 99 | +├── config |
| 100 | +│ └── module.config.php # Contains routing information and other module specific configurations. |
| 101 | +├── src |
| 102 | +│ ├── Command # CLI commands. |
| 103 | +│ │ └── ... |
| 104 | +│ ├── Controller # Entrypoint for requests to the website, some light processing takes place here before using a specific service. |
| 105 | +│ │ └── ... |
| 106 | +│ ├── Form # Specification and validation of forms based on entities. |
| 107 | +│ │ └── ... |
| 108 | +│ ├── Mapper # Doctrine ORM repositories to access the underlying database and mapping entities to that data. |
| 109 | +│ │ └── ... |
| 110 | +│ ├── Model # Doctrine ORM entities. |
| 111 | +│ │ └── ... |
| 112 | +│ └── Service # Services contain the core logic related to specific entities (or sets of entities) and do most of the processing. |
| 113 | +│ │ └── ... |
| 114 | +├── test # Test files for this module, such as unit tests. |
| 115 | +│ ├── Seeder # Data fixtures to seed the database with data for this module. |
| 116 | +│ │ └── ... |
| 117 | +│ └── ... |
| 118 | +└── view # All template files ("views") made out of HTML and PHP code, used by controllers for output. |
| 119 | + └── ... |
| 120 | +``` |
| 121 | + |
| 122 | +The `Application` module has two additional folders: |
| 123 | +- `language` containing the translation files (`make translations` to update them). |
| 124 | +- `migrations` containing database migrations. |
| 125 | + |
| 126 | +## License |
| 127 | +This software is licensed under the GNU General Public License v3.0 (GPL-3.0), see [LICENSE](./LICENSE.txt). |
0 commit comments